refacto on YAML config pages (#3697)

* split YAML doc pages, adding YAML structure for Upsun and solving small display issues * solve schema structure * change name of first top level yaml key to avoid confusion * P.sh YAML structure * remove duplicate lines * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/yaml/platform-yaml-tags.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/friday/src/learn/overview/yaml/yaml-structure.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Update sites/platform/src/learn/overview/get-support.md Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> * solve issue on link to express getting start guide * solve issue on link to express getting start guide * remove Express link as it does not exist on Upsun side * remove Express link as it does not exist on Upsun side * exclude file in alphabetical order * test with app-reference.html * test path with app-reference.md * test path app-reference.md * revert and keep .md * revert and keep .md * changing app-reference.md back to .html * Apply suggestions from code review Anouck's review Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> --------- Co-authored-by: AnouckColson <113913013+AnouckColson@users.noreply.github.com> Co-authored-by: Chad Carlson <chadwcarlson@users.noreply.github.com>
platformsh · Mar 6, 2024 · 8cde55e · 8cde55e
1 parent 3c8890d
commit 8cde55e
Show file tree

Hide file tree

Showing 16 changed files with 340 additions and 45 deletions.
diff --git a/sites/friday/config/_default/params.yaml b/sites/friday/config/_default/params.yaml
@@ -29,6 +29,7 @@ vendor:
     config:
         version: 2
         dir: .upsun
+        filename: config.yaml
         files:
             routes: .upsun/config.yaml
             services: .upsun/config.yaml

diff --git a/sites/friday/src/learn/overview/build-deploy.md b/sites/friday/src/learn/overview/build-deploy.md
@@ -98,4 +98,4 @@ Deployments to a staging or development branch have no impact on the production
 ## What's next
 
 * See how to [configure your app](/create-apps/_index.md) for the entire process.
-* Learn more about [using build and deploy hooks](/create-apps/hooks/_index.md).
+* Learn more about [using build and deploy hooks](/create-apps/hooks/_index.md).
diff --git a/sites/friday/src/learn/overview/get-support.md b/sites/friday/src/learn/overview/get-support.md
@@ -45,4 +45,4 @@ get in touch with [Sales](https://{{< vendor/urlraw "host" >}}/register/).
 ## Delete your account
 
 To permanently delete your {{% vendor/name %}} account,
-[contact Support](https://console.{{< vendor/urlraw "host" >}}/-/users/~/tickets/open).
+[contact Support](https://console.{{< vendor/urlraw "host" >}}/-/users/~/tickets/open).
diff --git a/sites/friday/src/learn/overview/philosophy.md b/sites/friday/src/learn/overview/philosophy.md
@@ -110,4 +110,4 @@ open a [support ticket](/learn/overview/get-support).
 ## What's next?
 
 To get a feeling of what working with {{% vendor/name %}} entails,
-see the [Get Started](/get-started/_index.md) framework guides.
+see the [Get Started](/get-started/_index.md) framework guides.
diff --git a/sites/friday/src/learn/overview/structure.md b/sites/friday/src/learn/overview/structure.md
@@ -4,6 +4,16 @@ weight: 2
 description: "Learn about how your {{% vendor/name %}} environments are structured and which files control that structure."
 ---
 
+{{< note version="1" >}}
+
+This page describes how things work on Grid projects.
+[{{% names/dedicated-gen-3 %}}](/dedicated-gen-3/_index.md) projects are similar,
+but they run on dedicated hosts and each container is replicated three times.
+
+For {{% names/dedicated-gen-2 %}} projects, read about how [{{% names/dedicated-gen-2 %}} projects are structured](/dedicated-gen-2/overview/_index.md).
+
+{{< /note >}}
+
 Each environment you deploy on {{% vendor/name %}} is built as a set of containers.
 Each container is an isolated instance with specific resources.
 
@@ -14,6 +24,7 @@ Each environment has 2 to 4 types of containers, all usually configured from you
 - Zero or more [*service* containers](#services)
 - Zero or more [*worker* containers](#workers)
 
+
 If you have two app containers, two services (a database and a search engine), and a worker,
 requests to your environment might look something like this:
 

diff --git a/sites/friday/src/learn/overview/yaml/_index.md b/sites/friday/src/learn/overview/yaml/_index.md
@@ -1,7 +1,7 @@
 ---
 title: YAML
 weight: 1
-description: "An overview of YAML and its use at {{% vendor/name %}}." 
+description: "An overview of YAML and its use at {{% vendor/name %}}."
 ---
 
 [YAML](https://en.wikipedia.org/wiki/YAML) is a human-readable format for data serialization across languages.

diff --git a/sites/friday/src/learn/overview/yaml/platform-yaml-tags.md b/sites/friday/src/learn/overview/yaml/platform-yaml-tags.md
@@ -1,6 +1,6 @@
 ---
 title: "{{% vendor/name %}} YAML tags"
-weight: 0
+weight: 10
 description: "A description of custom YAML tags available for {{% vendor/name %}} files."
 ---
 
@@ -54,7 +54,7 @@ applications:
     frontend:
         source:
             root: frontend
-        
+
         # ...
 
         hooks:
@@ -97,6 +97,50 @@ hooks:
 
 This helps you break longer configuration like build scripts out into a separate file for easier maintenance.
 
+Even if ``path`` is relative to the current application's directory, it is also possible to include a shell script from a directory parent to the folder however.
+
+For example, for the following project structure:
+
+```bash
+.
+├── {{< vendor/configdir >}}
+|   └── {{< vendor/configfile "apps" "strip" >}}
+├── backend
+│   ├── main.py
+│   ├── requirements.txt
+│   └── scripts
+│       ├── ...
+│       └── common_build.sh
+└── frontend
+    ├── README.md
+    ├── package-lock.json
+    ├── package.json
+    ├── public
+    ├── scripts
+    │   └── clean.sh
+    └── src
+```
+
+This configuration is valid:
+
+```yaml {configFile="apps"}
+applications:
+    frontend:
+        source:
+            root: frontend
+        # ...
+        hooks:
+            build: !include
+                type: string
+                path: ../backend/scripts/common_build.sh
+```
+
+{{% note theme="info" %}}
+
+Please note that {{% vendor/name %}} will execute this ``../backend/scripts/common_build.sh`` script using [Dash](https://wiki.archlinux.org/title/Dash).
+
+{{% /note %}}
+
 ### `binary`
 
 Use `binary` to include an external binary file inline in the YAML file.
@@ -106,7 +150,7 @@ For example, you could include a `favicon.ico` file in the same folder as your a
 Then you can include it as follows:
 
 ```yaml {configFile="app"}
-properties:
+some-property:
     favicon: !include
         type: binary
         path: favicon.ico
@@ -144,7 +188,7 @@ workers:
 
 ```yaml {configFile="app"}
 workers:
-    queue1: 
+    queue1:
         size: S
         commands:
             start: python queue-worker.py
@@ -155,6 +199,31 @@ workers:
 
 This can help simplify more complex files.
 
+
+For [multiple application](/create-apps/multi-app/_index.md) project, you can also include another ``.upsun/apps/my-app.yaml`` file in the main `{{% vendor/configfile "apps" %}}`.
+
+```yaml {location=".upsun/apps/my-app.yaml"}
+source:
+root: "/"
+type: "nodejs:18"
+web:
+    commands:
+      start: "node index.js"
+upstream:
+    socket_family: tcp
+locations:
+    "/":
+        passthru: true
+```
+
+and including it:
+
+```yaml {configFile="apps"}
+applications:
+  app:
+    !include ./apps/my-app.yaml
+```
+
 ## Archive
 
 Use the `!archive` tag for a reference to an entire directory specified relative to where the YAML file is.

diff --git a/sites/friday/src/learn/overview/yaml/what-is-yaml.md b/sites/friday/src/learn/overview/yaml/what-is-yaml.md
@@ -136,14 +136,14 @@ applications:
     myapp:
         hooks:
             build: |
-                set -e
+                set -x -e
                 cp a.txt b.txt
 ```
 
 And the resulting value preserves the line break.
 This lets you do things like enter small shell scripts within a YAML file.
 
-`hooks` → `build` → `set -e` and `cp a.txt b.txt`
+`hooks` → `build` → `set -x -e` and `cp a.txt b.txt`
 
 ## Reuse content
 
@@ -165,7 +165,7 @@ applications:
                 commands:
                     start: python queue-worker.py
             queue2: *runner
-            queue3: 
+            queue3:
                 <<: *runner
 ```
 

diff --git a/sites/friday/src/learn/overview/yaml/yaml-structure.md b/sites/friday/src/learn/overview/yaml/yaml-structure.md
@@ -0,0 +1,91 @@
+---
+title: "{{% vendor/name %}} YAML structure"
+weight: -5
+description: "A description of the YAML file for {{% vendor/name %}}."
+---
+
+In addition to the [basic functions you should be familiar with](./what-is-yaml.md), YAML structure is important.
+{{% vendor/name %}} accepts a specific structure for YAML configuration files.
+
+## YAML file location
+
+When you run the [`upsun project:init` command](/get-started/express/_index.md#configure-your-project), a default ``config.yaml`` file is generated in the `.upsun` folder. It contains the minimum default configuration based on your detected local stack.
+This YAML file is located in your ``.upsun`` directory, at the root of your project source code, and is a good starting point before customization.
+
+```bash
+.
+├── {{< vendor/configdir >}}
+|   └── {{< vendor/configfile "apps" "strip" >}}
+└── <source code>
+```
+## Mandatory top-level keys
+In the ``config.yaml`` file, there are only three mandatory top-level YAML keys:
+- ``applications``: this section of the file contains all of your [app definitions](/create-apps/app-reference.html)
+- ``routes``: this section of the file contains all of your [route definitions](/define-routes.md) (for each of your apps)
+- ``services``: this section of the file contains all of your [service definitions](/add-services.md) (for each of your apps)
+
+This looks like:
+```yaml {location="{{< vendor/configfile "apps" >}}"}
+{{< code-link destination="/create-apps/app-reference.md" text="applications" title="Complete list of all available properties" >}}:
+  app:
+    ...
+
+{{< 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 # All available versions are: 10.6, 10.5, 10.4, 10.3
+
+{{< code-link destination="/define-routes.md" text="routes" title="The routes of the project. Each route describes how an incoming URL is going to be processed by Upsun (Staging). Click for more information." >}}:
+  "https://{default}/":
+    type: upstream
+    upstream: "app:http"
+```
+
+Below these three top-level key sections, you can use any of the [available YAML tags](./yaml-structure.md) you need.
+
+{{% note %}}
+Any YAML files located at the first level of your ``.upsun`` folder, at the root of your project source code, are taken in account. See [Rules on YAML files](#rules-on-yaml-files).
+{{% /note %}}
+
+## Rules on YAML files
+The following rules apply to YAML files contained in the ``.upsun`` folder:
+
+- All the existing YAML files located at the first level of the ``.upsun`` folder are taken into account.
+- All the existing YAML files located at the first level of the ``.upsun`` folder must feature the [mandatory top-level keys](#mandatory-top-level-keys), and must contain a [valid YAML configuration](/create-apps/app-reference.md).
+- All the YAML files in subdirectories of the ``.upsun`` folder need to be [manually imported](/learn/overview/yaml/platform-yaml-tags.md#include) and contain a [valid YAML configuration](/create-apps/app-reference.md).
+
+{{% note title="Warning" theme="warning"%}}
+When {{% vendor/name %}} combines all the YAML files located at the first level of the ``.upsun`` folder, only the top-level keys (`applications`, `services`, and `routes`) are merged. So if you define an app named ``app`` in two different YAML files, {{% vendor/name %}} only takes the second one into account.
+
+Example:
+```yaml {location=".upsun/app.yaml"}
+applications:
+  app:
+    type: nodejs:16
+    source:
+      root: folder1
+    ...
+```
+
+```yaml {location=".upsun/app-bis.yaml"}
+applications:
+  app:
+    type: nodejs:20
+    build:
+      flavor: none
+    ...
+```
+
+Once {{% vendor/name %}} has combined the two configuration files,
+the blended configuration will be the following:
+```yaml {location="YAML config result"}
+applications:
+  app:
+    type: nodejs:20
+    build:
+      flavor: none
+    ...
+```
+
+Note that ``source.root`` (and any other `.upsun/app.yaml` parameters) will *not* be included in the final configuration.
+
+{{% /note %}}
diff --git a/sites/platform/config/_default/params.yaml b/sites/platform/config/_default/params.yaml
@@ -25,6 +25,7 @@ vendor:
     config:
         version: 1
         dir: .platform
+        filename: applications.yaml
         files:
             routes: .platform/routes.yaml
             services: .platform/services.yaml

diff --git a/sites/platform/src/create-apps/multi-app/project-structure.md b/sites/platform/src/create-apps/multi-app/project-structure.md
@@ -213,7 +213,7 @@ In that case, you can nest the Java app within the Python app:
 
 ```txt
 ├── {{% vendor/configdir %}}
-│   ├── {{% vendor/configfile "apps" %}}
+│   ├── {{% vendor/configfile "apps" "strip" %}}
 │   └── {{% vendor/configfile "routes" %}}
 ├── languagetool
 │   └── main.java           <- Java app code

diff --git a/sites/platform/src/learn/overview/build-deploy.md b/sites/platform/src/learn/overview/build-deploy.md
@@ -98,4 +98,4 @@ Deployments to a staging or development branch have no impact on the production
 ## What's next
 
 * See how to [configure your app](/create-apps/_index.md) for the entire process.
-* Learn more about [using build and deploy hooks](/create-apps/hooks/_index.md).
+* Learn more about [using build and deploy hooks](/create-apps/hooks/_index.md).
diff --git a/sites/platform/src/learn/overview/get-support.md b/sites/platform/src/learn/overview/get-support.md
@@ -45,4 +45,4 @@ get in touch with [Sales](https://{{< vendor/urlraw "host" >}}/contact/).
 ## Delete your account
 
 To permanently delete your {{% vendor/name %}} account,
-[contact Support](https://console.{{< vendor/urlraw "host" >}}/-/users/~/tickets/open).
+[contact Support](https://console.{{< vendor/urlraw "host" >}}/-/users/~/tickets/open).
diff --git a/sites/platform/src/learn/overview/philosophy.md b/sites/platform/src/learn/overview/philosophy.md
@@ -112,4 +112,4 @@ open a [support ticket](/learn/overview/get-support).
 ## What's next?
 
 To get a feeling of what working with {{% vendor/name %}} entails,
-see the [Get Started](/get-started/_index.md) framework guides.
+see the [Get Started](/get-started/_index.md) framework guides.