From df9ace1cd4fe8b99b4ee4c299c71a3846d574ca0 Mon Sep 17 00:00:00 2001 From: flovntp Date: Fri, 6 Oct 2023 10:23:31 +0200 Subject: [PATCH] Upsun Express Guide v0.1 (#3437) * Upsun Express Guide v0.1 * FHK: refacto Express guide * adding title shortcode code-link + improve Express guide * Express guide v1.0 * rework on Express guide * adding .gitignore file + small improvements * changing 'Git Flow' to 'Git workflow' * adding project:init screenshot + explain what it does * changing folder to my-express-app and add it in the folder schema * missing vendorisation * adding link to tutorial on how to create a project from the console * Adding a note telling readers that they can add services during project:init and link to add a database * remove git add . references to list exact files to commit * Add a database finished + adding 'Terminal' tab for all of the shell command snippets * missing terminal tab info * adding Add a database steps number * adding local development guide * remove useless envVar from .environment * Anouck's review - solve issues * Anouck's review - solve issues * remove extra lines to perform a redeploy :P * change .environment for having RELATIONSHIPS_JSON: empty by default during project:init with no service * solve Paul's review * adding extra line after all titles * changing add a hello world route paragraph * last review of changes from Anouck * adding create a project from CLI copy/paste to the Express guide * Update sites/friday/src/get-started/express/add-database.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/get-started/express/add-database.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * latest hidden comments... roooooh GH * Update sites/friday/src/get-started/express/add-database.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/get-started/express/add-database.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> --------- Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> --- sites/friday/config/_default/params.yaml | 9 +- .../friday/src/get-started/express/_index.md | 500 +++++++++++++++++- .../src/get-started/express/add-database.md | 248 +++++++++ sites/friday/src/get-started/express/local.md | 71 +++ sites/platform/config/_default/params.yaml | 11 +- .../layouts/shortcodes/code-link.html | 8 +- .../layouts/shortcodes/guides/requirements.md | 2 +- .../guides/whitelabel/git_integration.md | 41 ++ .../layouts/shortcodes/vendor/url_doc.html | 1 + 9 files changed, 878 insertions(+), 13 deletions(-) create mode 100644 sites/friday/src/get-started/express/add-database.md create mode 100644 sites/friday/src/get-started/express/local.md create mode 100644 themes/psh-docs/layouts/shortcodes/guides/whitelabel/git_integration.md create mode 100644 themes/psh-docs/layouts/shortcodes/vendor/url_doc.html diff --git a/sites/friday/config/_default/params.yaml b/sites/friday/config/_default/params.yaml index 236ecf169d..2b4873ab72 100644 --- a/sites/friday/config/_default/params.yaml +++ b/sites/friday/config/_default/params.yaml @@ -33,9 +33,9 @@ vendor: services: .upsun/config.yaml app: .upsun/config.yaml apps: .upsun/config.yaml - prefix: - apps: applications - services: services + prefix: + apps: applications + services: services routes: routes urls: main: https://upsun.com @@ -46,6 +46,7 @@ vendor: api: https://proxy.upsun.com/ host: upsun.com hostname: upsunapp.com + register: https://auth.upsun.com/register # Images (kept in static/) logo: "images/logo.svg" @@ -95,7 +96,7 @@ nonDocsSections: title: API Documentation link: https://proxy.upsun.com/docs weight: -80 - + # Metadata meta: sitename: "Upsun User Documentation" diff --git a/sites/friday/src/get-started/express/_index.md b/sites/friday/src/get-started/express/_index.md index 5f3f6faec9..df8fb69a5d 100644 --- a/sites/friday/src/get-started/express/_index.md +++ b/sites/friday/src/get-started/express/_index.md @@ -1,4 +1,500 @@ --- title: Express -description: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer dictum mauris id tincidunt gravida. Suspendisse sagittis euismod mi. Aliquam erat volutpat. ---- \ No newline at end of file +description: Welcome to our quick-start guide on hosting [Express](https://expressjs.com/) on {{< vendor/name >}} where we will demonstrate just how simple it is to host your [Express](https://expressjs.com/) projects on our PaaS. Follow the steps detailed below and you’ll have everything set up in no time. +--- + +{{% description %}} + +Anything included in these guides applies not only to [Express](https://expressjs.com/), but also to [NextJS](https://nextjs.org/) and [Strapi](https://strapi.io/). + +[//]: # (If you already have an Express project ready to deploy, jump directly to {{< vendor/cli >}}ify section.) + +[//]: # (These CLI command let you [configure your app](../../create-apps/_index.md),) + +[//]: # ([add services](../../add-services/_index.md), and [define routes](../../define-routes/_index.md).) + +{{% guides/link-philosophy %}} + +{{< note title=”tip” >}} +To get your Express project up and running as quickly as possible, experiment with the [{{% vendor/name %}} demo app](https://console.upsun.com/projects/create-project/demo) before following this guide. +{{< /note >}} + +{{% guides/requirements name="Express" %}} + +## Create your local Express app + +First things first, if you don’t have a local Express project, you need to create a new Express project locally by following the official Express [installation guide](https://expressjs.com/en/starter/installing.html). + +Please refer to all the steps of the official Express installation guide for further details, but to sum it up, this is the 4 steps to create an Express app locally: + +```bash {location="Terminal"} +mkdir my-express-app +cd my-express-app +npm init +npm install express +``` + +## Init your Git repo + +We need to initialize the local Git repository and commit local files, using the following command: + +```bash {location="Terminal"} +git init +git add package.json package-lock.json +git commit -m "Init Express application" +``` + +We should also ignore adding ``node_modules`` folder to the Git repository. Use the following commands to do so: + +```bash {location="Terminal"} +echo "/node_modules" >> .gitignore +git add .gitignore && git commit -m "adding node_modules folder in .gitignore file" +``` + +## Add a Hello World route + +Please create your first Express page. +To do so, create a new `index.js` file at the root of your project. It will contain a basic Hello world script: + +```javascript {location="index.js"} +const express = require('express') +const app = express() +var port = (process.env.PORT || '3000'); + +app.get('/', (req, res) => { + res.send('Hello World!') +}) + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`) +}) +``` + +Then please commit your file using the following commands: + +```bash {location="Terminal"} +git add index.js +git commit -m "adding index.js" +``` + +## Create a new project + +The next step is to create a project on {{% vendor/name %}}. +To do this, you can either use the {{% vendor/name %}} CLI or the {{% vendor/name %}} Console. + +{{< codetabs >}} ++++ +title=Using the CLI ++++ +To create a new project with the {{% vendor/name %}} CLI, use the following command and follow the prompt: +```bash {location="Terminal"} +{{% vendor/cli %}} project:create +``` + +{{< note >}} +When creating a new project using the {{% vendor/name %}} CLI command `project:create`, you will be asked if you want to set the local remote to your new project. Enter **Yes (y)**. +Your local source code will be automatically linked to your newly created {{% vendor/name %}} project by creating a `.{{% vendor/cli %}}/local/project.yaml` file that will contain the corresponding `` and set a Git remote to `{{% vendor/cli %}}`. + +```bash {location="Terminal"} +git remote +{{% vendor/cli %}} +``` + +If not, please refer to [Set project remote](#set-project-remote) section. +{{< /note >}} + +<---> ++++ +title=Using the Console ++++ + +[Create a new project from scratch]({{% vendor/urlraw "console" %}}/projects/create-project/). + +If you do not already have an organization created to put the project, you'll first be instructed to create one. + +Once you have done so, select that organization from the dropdown, and select **Create from scratch**. + +In the form, fill in details like the project name and [region](/development/regions.md). +You'll be able to define resources for the project after your first push. + +After creating a project with the console, you need to let the {{% vendor/name %}} CLI know which linked project you want to deploy to. + +To do so, use the {{% vendor/name %}} CLI to set remote project: +```bash {location="Terminal"} +{{% vendor/cli %}} project:set-remote +``` + +This command will add a new remote called `{{% vendor/cli %}}` to your local Git repo as you can see below: +```bash {location="Terminal"} +git remote +origin +{{% vendor/cli %}} +``` + +It will also create a new `.{{% vendor/cli %}}/local/project.yaml` file that will contain the given ``, to store this info for the {{% vendor/name %}} CLI interaction. + +{{< note >}} +If you don’t remember your `` from the previous steps, you can get it back using this command line and select the one you created: +```bash {location="Terminal"} +{{% vendor/cli %}} project:list +``` +{{< /note >}} + +{{< /codetabs >}} + +## Choose your Git workflow + +{{% vendor/name %}} projects can be used as a classic Git repository where you will be able to push your source code in different ways using either Git CLI or {{% vendor/name %}} CLI. You can choose which way—or Git workflow—you would like to use for your project from the following options: + +- Your project source code will be **hosted on a {{% vendor/name %}} Git repository** +- Your project source code will be **hosted on your own GitHub repository** + +{{< codetabs >}} ++++ +title={{% vendor/name %}} Git repository ++++ +For the rest of this guide, you will use the normal Git workflow (`git add . && git commit -m "message" && git push`) to commit your source code changes to Git history, and use {{% vendor/name %}} CLI to deploy your [{{% vendor/name %}} environment](/environments.html) with latest code updates. + +<---> ++++ +title=GitHub repository ++++ +{{% vendor/name %}} provides a feature called [Github integration](integrations/source/github.md) that allows your {{% vendor/name %}} project to be fully integrated with your Github repository. +Enabling you, as a developer, to use a normal Git workflow (`git add . && git commit -m "message" && git push`) to deploy your environment—with no need to connect to the {{% vendor/name %}} console. + +{{< note >}} +Please make sure you that you have already completed the following steps before adding a [Github integration](integrations/source/github.md): + +1. Create a Git repository in your own organization following the relevant [Github repository creation guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). +2. Create a [Github integration](integrations/source/github.md). +3. Add a Git remote to your local project, from the root of your Express directory, by inputting the following: + ```bash {location="Terminal"} + git remote add origin + git add . && git commit -m "init express" + git push origin + ``` +{{< /note >}} + +{{< /codetabs >}} + +## Configure your project + +To be able to host your Express application on {{% vendor/name %}}, some YAML configuration files are needed at the root of your project to manage the way your application will behave. +These YAML configuration files are located into a `.{{% vendor/cli %}}/` folder at the root of your source code, the architecture of which will look like this: +``` +my-express-app +├── .{{% vendor/cli %}} +│ └── config.yaml +├── .environment +└── +``` + +{{< note >}} +An additional `.environment` file is located at the root of your source code, this file will override `.env` environment variables with {{% vendor/name %}} specific ones. +{{< /note >}} + +To pre-generate these YAML files, please use the following command from the root of your Express project and follow the prompts: +```bash {location="Terminal"} +{{% vendor/cli %}} project:init +Welcome to {{% vendor/name %}}! +Let's get started with a few questions. + +We need to know a bit more about your project. This will only take a minute! + +✓ Detected stack: Express +✓ Detected runtime: JavaScript/Node.js +✓ Detected dependency managers: Npm +Tell us your project name: [app] + + (\_/) +We’re almost done... =(^.^)= + +Last but not least, unless you’re creating a static website, your project uses services. Let’s define them: + +Select all the services you are using: [] + +You have not selected any service, would you like to proceed anyway? [Yes] + +┌───────────────────────────────────────────────────┐ +│ CONGRATULATIONS! │ +│ │ +│ We have created the following files for your: │ +│ - .environment │ +│ - .{{% vendor/cli %}}/config.yaml │ +│ │ +│ We’re jumping for joy! ⍢ │ +└───────────────────────────────────────────────────┘ + │ / + │/ + │ + (\ /) + ( . .) + o (_(“)(“) + +You can now deploy your application to {{% vendor/name %}}! +To do so, commit your files and deploy your application using the {{% vendor/name %}} CLI: + $ git add . + $ git commit -m 'Add {{% vendor/name %}} configuration files' + $ {{% vendor/cli %}} push + $ git add . && git commit -m "Init project" +``` + +The `{{% vendor/cli %}} project:init` command (shortcut `{{% vendor/cli %}} ify`) will automatically detect that you’re using an Express stack, ask if you want to add any services, and generate the corresponding `config.yaml` YAML files, like so: +```yaml {location=".{{% vendor/cli %}}/config.yaml"} +{{< code-link destination="/create-apps/app-reference.html" text="applications" title="Complete list of all available properties" >}}: + app: + {{< code-link destination="/create-apps/app-reference.html#source" text="source" title="Application source code directory. Click for more information" >}}: + root: "/" + {{< code-link destination="/create-apps/app-reference.html#types" text="type" title="The runtime the application uses. Click to see the complete list of available runtimes." >}}: "nodejs:18" + {{< code-link destination="/create-apps/app-reference.html#types" text="web" title="The web key configures the web server running in front of your app. Click for more information." >}}: + {{< code-link destination="/create-apps/app-reference.html#web-commands" text="commands" title="Commands are run once after deployment to start the application process. Click for more information." >}}: + {{< code-link destination="/languages/nodejs.html#4-start-your-app" text="start" title="The command to launch your app. If it terminates, it’s restarted immediately. You can use the $PORT or the $SOCKET environment variable depending on the socket family of your upstream. Click for more information." >}}: "node index.js" + {{< code-link destination="/create-apps/app-reference.html#build" text="build" title="Specifies a default set of build tasks to run. Flavors are language-specific. Click for more information" >}}: + flavor: none + {{< code-link destination="/create-apps/app-reference.html#web-commands" text="dependencies" title="Installs global dependencies as part of the build process. They’re independent of your app’s dependencies and are available in the PATH during the build process and in the runtime environment. They’re installed before the build hook runs using a package manager for the language. Click for more information." >}}: + nodejs: + sharp: "*" +#services: +# db: +# type: postgresql:15 +routes: + "https://{default}/": + type: upstream + upstream: "app:http" + # A basic redirect definition + # More information: {{% vendor/url_doc %}}/define-routes.html#basic-redirect-definition + "https://www.{default}/": + type: redirect + to: "https://{default}/" +``` + +{{< note >}} +In the current guide, services are added to your project at a [later stage](/get-started/express/add-database.md). +{{< /note >}} + +Then commit your new files, using the following command: + +```bash {location="Terminal"} +git add .environment .{{% vendor/cli %}}/config.yaml +git commit -m "{{% vendor/name %}} config files" +``` + +## Set project remote + +{{< note >}} +If you used the {{% vendor/name %}} CLI command `{{% vendor/cli %}} project:create` to create your project and your local Git repo has already been initialized, your local source code should already contain a ``.{{% vendor/cli %}}/local/project.yaml`` file. This file contains your `projectId`, and you already have a Git remote repository set to `{{% vendor/cli %}}`. +You can jump to [deploying your project](#deploy). +{{< /note >}} + +There are slightly different ways to link your local project to your {{% vendor/name %}} project based on the Git workflow you chose for you project as discussed earlier in this guide. + +{{< codetabs >}} ++++ +title={{% vendor/name %}} Git repository ++++ +If you host your Express source code on an {{% vendor/name %}} Git repository, and you failed to answer `y` (yes) to the question `Set the new project as the remote for this repository? [Y/n]` during the ``project:create`` command, you need to let the {{% vendor/name %}} CLI know which linked project you want to deploy to. + +To do so, use the {{% vendor/name %}} CLI to set remote project: +```bash {location="Terminal"} +{{% vendor/cli %}} project:set-remote +``` + +This command will add a new remote called `{{% vendor/cli %}}` to your local Git repo as you can see below: +```bash {location="Terminal"} +git remote +{{% vendor/cli %}} +... +``` + +It will also create a new `.{{% vendor/cli %}}/local/project.yaml` file that will contain the given ``, to store this info for the {{% vendor/name %}} CLI interaction. + +{{< note >}} +If you don’t remember your `` from the previous steps, you can get it back using this command line and select the one you created: +```bash {location="Terminal"} +{{% vendor/cli %}} project:list +``` +{{< /note >}} + +<---> ++++ +title=GitHub repository ++++ +{{% guides/whitelabel/git_integration git="GitHub" stack="Express" %}} +<---> ++++ +title=Gitlab repository ++++ +{{% guides/whitelabel/git_integration git="Gitlab" stack="Express" %}} +<---> ++++ +title=Bitbucket repository ++++ +{{% guides/whitelabel/git_integration git="Bitbucket" stack="Express" %}} + +{{< /codetabs >}} + +## Deploy + +And just like that, it’s time to deploy! + +Depending on the Git workflow you choose at the beginning of this tutorial, there are two ways to deploy your source code changes. + +{{< codetabs >}} + ++++ +title=Using {{% vendor/name %}} Git repository ++++ + +When using the {{% vendor/name %}} Git repository as your main repository, you can push your code using the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your source code changes to your `{{% vendor/cli %}}` remote repository. Alternatively, you can use the following {{% vendor/name %}} CLI command: +```bash {location="Terminal"} +{{% vendor/cli %}} push +``` + +<---> ++++ +title=Using third-party Git repository ++++ + +When using an external Git repository (Github, Gitlab, or Bitbucket) to store your source code and having the Git integration feature enabled, on each code updates, you will need to use the normal Git workflow (`git add . && git commit -m "message" && git push`) to push your code to your external repository. To do so, run the following command: +```bash {location="Terminal"} +git push origin +``` + +Your Github/Gitlab/Bibucket integration process will then automatically create a new environment if you’re pushing a new Git branch, and deploy changes to your corresponding environment. +{{< /codetabs >}} + +{{% vendor/name %}} will now read your configuration files, and begin building your application image. **Your first push +will fail**; don't worry, this is expected. At this point {{% vendor/cli %}} is not aware of the resources +your application needs. You need to define how much CPU, memory, and disk to assign to the various containers. Back in your terminal, run: + +```bash {location="Terminal"} +{{% vendor/cli %}} resources:set +``` + +This will launch an interactive prompt to walk you through setting up your application's resources: +```bash {location="Terminal"} +{{% vendor/cli %}} resources:set +Resource configuration for the project app (123456azerty), environment main (type: production): ++-----------------------+---------+---------+-------------+-----------+-----------+ +| App or service | Size | CPU | Memory (MB) | Disk (MB) | Instances | ++-----------------------+---------+---------+-------------+-----------+-----------+ +| app | not set | not set | not set | N/A | 1 | ++-----------------------+---------+---------+-------------+-----------+-----------+ +``` +The first question is what profile size you want applied to your application image. For now let's select the minimum `0.1`: +```bash {location="Terminal"} +App: app +Choose a profile size: + [0.1 ] CPU 0.1, memory 64 MB + [0.25] CPU 0.25, memory 128 MB + [0.5 ] CPU 0.5, memory 224 MB + [1 ] CPU 1, memory 384 MB + [2 ] CPU 2, memory 704 MB + [4 ] CPU 4, memory 1216 MB + [6 ] CPU 6, memory 1728 MB + [8 ] CPU 8, memory 2240 MB + [10 ] CPU 10, memory 2688 MB + > 0.1 +``` +Next it will ask how many instances of our application container we need deployed. For now let's go with `1`: +```bash {location="Terminal"} +Enter the number of instances (default: 1): 1 +``` + +Last it will ask us to confirm our choices. Select `Y` and the {{% vendor/name %}} will take your selections, grab the +previous built images from early, apply our resource selections to them and deploy our full application! + +Note that each environment has its own domain name. +To open the url of your new environment, run the following command: + + ```bash {location="Terminal"} + {{% vendor/cli %}} environment:url --primary + ``` + +Et voilà, your Express application is live! + +## Make changes to your project + +Now that your project is deployed, you can start making changes to it. +For example, you might want to fix a bug or add a new feature. + +In your project, the `main` branch always represents the production environment. +Other branches are for developing new features, fixing bugs, or updating the infrastructure. + +To make changes to your project, follow these steps: + +1. Create a new environment (a Git branch) to make changes without impacting production: + + ```bash {location="Terminal"} + {{% vendor/cli %}} branch feat-a + ``` + + This command creates a new local `feat-a` Git branch based on the main Git branch + and activates a related environment on {{< vendor/name >}}. + The new environment inherits the data (service data and assets) of its parent environment (the production environment here). + +2. Make changes to your project. + + For example, edit the `./index.js` file and make the following changes: + + ```javascript {location="index.js"} + app.get('/', async function(req, res){ + // Make the output. + const outputString = `Hello, World! - A simple Express web framework template for {{% vendor/name %}}` + res.send(outputString); + }); + ``` + +3. Commit your changes: + + ```bash {location="Terminal"} + git add index.js + git commit -m "Update Hello world" + ``` + +4. Deploy your changes to the `feat-a` environment: + + ```bash {location="Terminal"} + {{% vendor/cli %}} push + ``` + + Note that each environment has its own domain name. + To open the url of your new environment, run the following command: + + ```bash {location="Terminal"} + {{% vendor/cli %}} environment:url --primary + ``` + +5. Iterate by changing the code, committing, and deploying. + When satisfied with your changes, merge them to the main branch, + and remove the feature branch: + + ```bash {location="Terminal"} + {{% vendor/cli %}} merge + Are you sure you want to merge feat-a into its parent, main? [Y/n] y + {{% vendor/cli %}} checkout main + git pull {{% vendor/cli %}} main + {{% vendor/cli %}} environment:delete feat-a + git fetch --prune + ``` + + {{< note >}} + Deploying to production was fast because the image built for the `feat-a` environment was reused. + {{< /note >}} + + For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`. + You can also keep the data in sync with the production environment by using `{{% vendor/cli %}} env:sync`. + +## Use a third-party Git provider + +When you choose to use a third-party Git hosting service, the {{< vendor/name >}} Git +repository becomes a read-only mirror of the third-party repository. All your +changes take place in the third-party repository. + +Add an integration to your existing third-party repository: + +- [BitBucket](/integrations/source/bitbucket.md) +- [GitHub](/integrations/source/github.md) +- [GitLab](/integrations/source/gitlab.md) + +## Next steps diff --git a/sites/friday/src/get-started/express/add-database.md b/sites/friday/src/get-started/express/add-database.md new file mode 100644 index 0000000000..257b330545 --- /dev/null +++ b/sites/friday/src/get-started/express/add-database.md @@ -0,0 +1,248 @@ +--- +title: "Add a database" +weight: -130 +description: | + Once Your Express application has been deployed on {{% vendor/name %}}, you might want to add a service to your application. +--- + +{{% description %}} + +{{% vendor/name %}} projects already include a [variety of services](/add-services.html#available-services), so you don’t have to subscribe to an external cache or search-engine services. +And as these services are included in your project, you can manage them through Git and they’re backed up along with the rest of your project. +Your project source code defines the services configuration in the main `.{{% vendor/cli %}}/config.yaml` file, and this is where you can add new services. + +As an example on how to do so, to add a [MariaDB database engine](/add-services/mysql.html) into your Express project, complete the following 6 steps: + +## 1. Create a new branch for testing + +Create a new branch using the following command: +```bash {location="Terminal"} +{{% vendor/cli %}} environment:branch add-mysql-database +``` + +## 2. Add a MariaDB service + +Configure the MariaDB service by adding this Yaml definition at the end of your `.{{% vendor/cli %}}/config.yaml` file: + +```yaml {location=".{{% vendor/cli %}}/config.yaml"} +{{< code-link destination="/add-services.html#available-services" text="services" title="Click to see the complete list of all available services" >}}: + mariadb: + type: mariadb:10.6 +``` + +Connect the service to your application ``app`` by adding a relationships setting into your `app` definition: +```yaml {location=".{{% vendor/cli %}}/config.yaml"} +applications: + app: + type: nodejs:18 + {{< code-link destination="/create-apps/app-reference.html#relationships" text="relationships" title="The relationships of the application with services or other applications. The left-hand side is the name of the relationship as it will be exposed to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand side is in the form `:`. Click for more information." >}}: + mariadb: "mariadb:mysql" +``` + +Add into your ``.environment`` file the following lines: +```shell {location=".environment"} +export RELATIONSHIPS_JSON="$(echo $PLATFORM_RELATIONSHIPS | base64 --decode)" + +# Set database environment variables +export DB_HOST="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].host')" +export DB_PORT="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].port')" +export DB_DATABASE="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].path')" +export DB_USERNAME="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].username')" +export DB_PASSWORD="$(echo $RELATIONSHIPS_JSON | jq -r '.mariadb[0].password')" +``` + +{{< note >}} +This additional `.environment` file is located at the root of your source code. During deployment of your {{% vendor/name %}} project, this file will override existing `.env` environment variables with {{% vendor/name %}} specific ones. +{{< /note >}} + +Commit your change: +```bash {location="Terminal"} +git add .environment .{{% vendor/cli %}}/config.yaml && git commit -m "adding MariaDb database service" +{{% vendor/cli %}} push +``` + +{{< note >}} +{{% vendor/name %}} will now read your configuration files, and begin building your application image. **Your push +will fail**; don't worry, this is expected. At this point {{% vendor/cli %}} is not aware of the resources +our new service needs. You need to define how much CPU, memory, and disk to assign to the service container. + +Please complete [Configure resources for your service](#3-configure-resources-for-your-service) step +{{< /note >}} + +## 3. Configure resources for your service + +When you push a new service to your project for the first time, the deployment will fail, and you will need to allocate resources to the service container. + +Back in your terminal, run: + +```shell +{{% vendor/cli %}} resource:set --size mariadb:0.5 --disk mariadb:512 + Resource configuration for the project My Express App 0926 (12345azerty), environment feat-database (type: development): + +------------------+------+-----+-------------+-----------+-----------+ + | App or service | Size | CPU | Memory (MB) | Disk (MB) | Instances | + +------------------+------+-----+-------------+-----------+-----------+ + | app | 0.1 | 0.1 | 384 | N/A | 1 | + | mariadb | 0.5 | 0.5 | 1408 | 512 | 1 | + +------------------+------+-----+-------------+-----------+-----------+ + +Summary of changes: + Service: mariadb + CPU: 0.5 + Memory: 1408 MB + Disk: 512 MB + +Are you sure you want to continue? [Y/n] y +``` + +## 4. Configure your Express application to use this new database + +First, you need a NodeJs module named ``mysql2``. Install it by running the following command: +```bash {location="Terminal"} +npm install mysql2 +``` + +Then modify your index.js with the following : +```javascript {location="index.js"} +const express = require('express') +const app = express() +const mysql = require("mysql2/promise"); +const port = (process.env.PORT || '3000'); + +function openConnection() { + return mysql.createConnection({ + host: process.env.DB_HOST, + port: process.env.DB_PORT, + user: process.env.DB_USERNAME, + password: process.env.DB_PASSWORD, + database: process.env.DB_DATABASE + }); +} + +function createTable(connection) { + return connection.execute( + `CREATE TABLE IF NOT EXISTS {{% vendor/cli %}}info ( + uid INT(10) NOT NULL AUTO_INCREMENT, + username VARCHAR(64) NULL DEFAULT NULL, + departname VARCHAR(128) NULL DEFAULT NULL, + created DATE NULL DEFAULT NULL, + PRIMARY KEY (uid) + ) DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;` + ); +} + +function insertData(connection) { + return connection.execute( + "INSERT INTO {{% vendor/cli %}}info (username, departname, created) VALUES ('{{% vendor/cli %}}', 'Deploy Friday', '2023-09-29')" + ); +} + +function readData(connection) { + return connection.query("SELECT * FROM {{% vendor/cli %}}info"); +} + +function dropTable(connection) { + return connection.execute("DROP TABLE {{% vendor/cli %}}info"); +} + +// Define the main route. +app.get('/', async function(req, res){ + + // Connect to MariaDB. + const connection = await openConnection(); + + await createTable(connection); + await insertData(connection); + + const [rows] = await readData(connection); + + const droppedResult = await dropTable(connection); + + // Make the output. + const outputString = `Hello, World! - A simple Express web framework template for {{% vendor/name %}} + +MariaDB Tests: + +* Connect and add row: + - Row ID (1): ${rows[0].uid} + - Username ({{% vendor/cli %}}): ${rows[0].username} + - Department (Deploy Friday): ${rows[0].departname} + - Created (2023-09-29): ${rows[0].created} +* Delete row: + - Status (0): ${droppedResult[0].warningStatus}`; + + res.set('Content-Type', 'text/plain'); + res.send(outputString); +}); + +// Get PORT and start the server +app.listen(port, function() { + console.log(`Listening on port ${port}`) +}); +``` + +Commit your changes and deploy your changes: +```bash {location="Terminal"} +git add package.json package-lock.json index.js && git commit -m "adding MariaDb database service" +{{% vendor/cli %}} push +{{% vendor/cli %}} environment:url --primary +``` + +## 5. Merge to production + +When satisfied with your changes, merge them to the main branch, and remove the feature branch: + +```bash {location="Terminal"} +{{% vendor/cli %}} merge + Are you sure you want to merge add-mysql-database into its parent, main? [Y/n] y +``` + +{{< note >}} +{{% vendor/name %}} will now read your configuration files, and begin building your application image. **Your push +will fail**; don't worry, this is expected. At this point {{% vendor/cli %}} is not aware of the resources +our new service needs. We need to tell it what kind of CPU, Memory, and disk to assign to the service container. + +Please complete again [Configure resources for your service](#3-configure-resources-for-your-service) step +{{< /note >}} + + +## 6. Remove the feature branch + +Then, you need to remove the feature branch +```bash {location="Terminal"} +{{% vendor/cli %}} checkout main +git pull {{% vendor/cli %}} main +{{% vendor/cli %}} environment:delete add-mysql-database +git fetch --prune +``` + +{{< note >}} +During ``environment:delete`` CLI command, it will ask question regarding deactivation and deletion of your `add-mysql-database` environment. Please say `yes` (`y`) to all of them. +{{< /note >}} + +## Tip&Tricks + +You can get your project relationships information using the following command: +```bash {location="Terminal"} +{{% vendor/cli %}} relationships + ... + mariadb: + - + username: user + scheme: mysql + service: mariadb + fragment: null + ip: 198.12.123.45 + hostname: abcdefghijklm1234567890123.mariadb.service._..{{< vendor/urlraw "hostname" >}} + public: false + cluster: abcdefgh1234567-add-mysql-database-abcd123 + host: mariadb.internal + rel: mysql + query: + is_master: true + path: main + password: '' + type: 'mariadb:10.6' + port: 3306 + host_mapped: false + url: 'mysql://user:@mariadb.internal:3306/main' +``` diff --git a/sites/friday/src/get-started/express/local.md b/sites/friday/src/get-started/express/local.md new file mode 100644 index 0000000000..98c27532eb --- /dev/null +++ b/sites/friday/src/get-started/express/local.md @@ -0,0 +1,71 @@ +--- +title: "Local development" +weight: -120 +description: | + Once Your Express application has been deployed on {{% vendor/name %}}, you might want to start develop your application locally. +--- + +{{% description %}} + +{{% guides/link-philosophy %}} + +{{% guides/requirements name="Express" %}} +* Install [node CLI](https://nodejs.org/en/download/package-manager) (version >= 18.x) +* Install [Docker Composer](https://docs.docker.com/compose/install/) locally + +## Create a MariaDb Docker container + +At the root of your project, create a ``docker-composer.yaml`` file with the following: + +```bash {location="docker-compose.yaml"} +version: '3' +volumes: + data: +services: + db: + image: mariadb + environment: + MYSQL_ROOT_PASSWORD: password + MYSQL_DATABASE: express + MYSQL_USER: user + MYSQL_PASSWORD: password + volumes: + - data:/var/lib/mysql + ports: + - "3306:3306" +``` + +And launch corresponding Docker container: +```bash {location="Terminal"} +docker-compose up -d +``` + +## Adapt your Express application to use local Docker container + +For your Express application to use the local Docker container, adapt your ``index.js`` file, function `openConnection()` with the following : +```javascript +... +function openConnection() { + return mysql.createConnection({ + host: (process.env.DB_HOST || '127.0.0.1'), + port: (process.env.DB_PORT || '3306'), + user: (process.env.DB_USERNAME || 'user'), + password: (process.env.DB_PASSWORD || 'password'), + database: (process.env.DB_DATABASE || 'express') + }); +} +... +``` + +## Launch local Express application + +To run your Express application locally, use the following: +```bash {location="Terminal"} +node index.js +``` + +And then open your favorite browser with http://localhost:3000. + +{{< note >}} +You might want your colleague to be able to do the same, so feel free to commit your changes on your favorite Git repository to share them with your team. +{{< /note >}} diff --git a/sites/platform/config/_default/params.yaml b/sites/platform/config/_default/params.yaml index 500f302e5d..d924ab1065 100644 --- a/sites/platform/config/_default/params.yaml +++ b/sites/platform/config/_default/params.yaml @@ -30,9 +30,9 @@ vendor: services: .platform/services.yaml app: .platform.app.yaml apps: .platform/applications.yaml - prefix: - apps: applications - services: services + prefix: + apps: applications + services: services routes: routes urls: main: https://platform.sh/ @@ -41,8 +41,9 @@ vendor: sales: https://platform.sh/contact console: https://console.platform.sh/ api: https://api.platform.sh/ - host: platform.sh - hostname: platformsh.site + host: platform.sh + hostname: platformsh.site + register: https://auth.api.platform.sh/register # Images (kept in static/) logo: "images/logos/Platformsh_logo_white.svg" diff --git a/themes/psh-docs/layouts/shortcodes/code-link.html b/themes/psh-docs/layouts/shortcodes/code-link.html index 889708203c..a11ae74b82 100644 --- a/themes/psh-docs/layouts/shortcodes/code-link.html +++ b/themes/psh-docs/layouts/shortcodes/code-link.html @@ -1 +1,7 @@ -{{ .Get "text" }} \ No newline at end of file +{{- $destination := .Get "destination" -}} +{{- $title := .Get "title" -}} +{{ if not $title }} + {{- $title = "Click for more information" -}} +{{ end }} +{{- $text := .Get "text" -}} +{{- printf "%s" $destination $title $text | chomp | safeHTML -}} diff --git a/themes/psh-docs/layouts/shortcodes/guides/requirements.md b/themes/psh-docs/layouts/shortcodes/guides/requirements.md index 4816022efd..94be678496 100644 --- a/themes/psh-docs/layouts/shortcodes/guides/requirements.md +++ b/themes/psh-docs/layouts/shortcodes/guides/requirements.md @@ -8,7 +8,7 @@ You need: Push commits to deploy changes and control configuration through YAML files. These files describe your infrastructure, making it transparent and version-controlled. - A {{ .Site.Params.vendor.name }} account. - If you don't already have one, [register for a trial account](https://auth.api.platform.sh/register). + If you don't already have one, [register for a trial account]({{ .Site.Params.vendor.urls.register }}). You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your {{ .Site.Params.vendor.name }} account later. - {{ if $isSymfony }}The [Symfony CLI](https://symfony.com/download){{ else }}Required: the [{{ .Site.Params.vendor.name }} CLI](/administration/cli/_index.md){{ end }}. diff --git a/themes/psh-docs/layouts/shortcodes/guides/whitelabel/git_integration.md b/themes/psh-docs/layouts/shortcodes/guides/whitelabel/git_integration.md new file mode 100644 index 0000000000..938701c533 --- /dev/null +++ b/themes/psh-docs/layouts/shortcodes/guides/whitelabel/git_integration.md @@ -0,0 +1,41 @@ +{{ $git := .Get "git" }} +{{ $stack := .Get "stack" }} +{{ $option := "" }} + +{{ if in $git "GitHub" }} + {{ $option = "2" }} +{{ end }} +{{ if in $git "Gitlab" }} + {{ $option = "3" }} +{{ end }} +{{ if in $git "Bitbucket" }} + {{ $option = "0" }} +{{ end }} + +We assume here that you already have your own {{ $git }} repository with the {{ $stack }} source code you want to host on {{ .Site.Params.vendor.name }}. +To link using this repository, use the following {{ .Site.Params.vendor.name }} CLI command to create a {{ $git }} integration with your project and then let the integration process create one environment per Git branch from your repository: + +```shell +$ upsun integration:add +* Integration type (--type) + Enter a number to choose: + [0 ] bitbucket + [1 ] bitbucket_server + [2 ] github + [3 ] gitlab + [4 ] webhook + [5 ] health.email + [6 ] health.pagerduty + [7 ] health.slack + [8 ] health.webhook + [10] script +> {{ $option }} + +* Token (--token) + An authentication or access token for the integration +> X1234567890AZERTYUIOP + +* Repository (--repository) + The repository (e.g. 'owner/repository') +> / +``` diff --git a/themes/psh-docs/layouts/shortcodes/vendor/url_doc.html b/themes/psh-docs/layouts/shortcodes/vendor/url_doc.html new file mode 100644 index 0000000000..4cbda62e46 --- /dev/null +++ b/themes/psh-docs/layouts/shortcodes/vendor/url_doc.html @@ -0,0 +1 @@ +{{- .Site.Params.rooturl -}}