Merge pull request #3643 from uselagoon/orgs-docs

Docs: Adding Organizations and Lagoonizing docs + reorganization

DEPRECATIONS.md

@@ -1,22 +1,24 @@
-
-
 # Lagoon Project Deprecation Announcements
 
 ## Overview
+
 This file is a constantly updated central tracker for deprecations across the suite of Lagoon products. As Lagoon continues to evolve, we occasionally need to replace, rename or retire existing processes, tools or configuration. Where this may impact a user's processes or procedures, we intend to outline a timeframe to allow any necessary changes to be made.
 
 Deprecations will be tracked by the release they are announced in, and then updated when the actual deprecation occurs. All deprecations should provide a rough timeline (in months or releases). Releases will normally only be listed here if they include planned deprecations.
 
 ## Deprecation History
+
 All deprecations are listed below, with the most recent announcements at the top.
 
 ### Lagoon v2.17.0
+
 release link: https://github.com/uselagoon/lagoon/releases/tag/v2.17.0
 * This release introduces a new active/standby task image that does not require the use of the [dioscuri controller](https://github.com/amazeeio/dioscuri). Dioscuri is deprecated and will eventually be removed from the `lagoon-remote` helm chart. If you use active/standby functionality in your clusters, you should upgrade to lagoon v2.17.0 and update your remote clusters to the version of the `lagoon-remote` helm chart the v2.17.0 release says to use (see release notes for v2.17.0)
 * Support for Harbor in the API will be removed in a future release. If you currently have your core installation with Harbor support, you should move to using the integration within lagoon-remote instead. See the documentation [here](https://docs.lagoon.sh/installing-lagoon/install-lagoon-remote) and read the section about Harbor.
 * Support for Harbor 2.1.x (chart version 1.5.x) and older in `lagoon-remote` will be removed in a future release. You should consider upgrading Harbor to a newer version (currently Lagoon supports up to v2.9.x (chart version 1.13.x)), following any recommended upgrade paths from Harbor.
 
 ### Lagoon v2.16.0
+
 release link: https://github.com/uselagoon/lagoon/releases/tag/v2.16.0
 
-There were no planned deprecations announced in this release.
+There were no planned deprecations announced in this release.

docs/README.md

@@ -6,14 +6,22 @@
 
 Lagoon gives developers what they dream about. It's a system that allows developers to run the exact same code in their local and production environment. The same Docker images, the same service configurations, and the same code.
 
-## Who are you?
+## Where do I start?
 
-<div class="grid cards" markdown>
+If you want to use Lagoon to host your website or application, visit
+[Using Lagoon - The Basics](using-lagoon-the-basics/index.md)
+
+To get more in depth with Lagoon functionality, visit
+[Using Lagoon - Advanced](using-lagoon-advanced/index.md)
+
+To understand how Lagoon works, check out
+[Lagoon Concepts - The Basics](concepts-basics/index.md)
+
+and for a deeper understanding, [Lagoon Concepts - Advanced](concepts-advanced/index.md)
+
+If you want to develop Lagoon \(add features, fix bugs\), [Developing Lagoon](contributing-to-lagoon/developing-lagoon.md)
 
-- If you want to use Lagoon to host your website or application, visit [Using Lagoon](using-lagoon-the-basics/index.md).
-- If you want to develop Lagoon \(add features, fix bugs\), [Developing Lagoon](contributing-to-lagoon/developing-lagoon.md).
 
-</div>
 ## TL;DR: How Lagoon Works
 
 1. Developers define and configure needed services within YAML files.

docs/drupal/automatic-updates.md → docs/applications/drupal/automatic-updates.md

@@ -20,13 +20,13 @@ runtime, it can cause any of the following problems:
 
 The following update methods been disabled by Lagoon.
 
-### Drupal Automatic Updates
+## Drupal Automatic Updates
 
 The [Automatic Updates](https://www.drupal.org/project/automatic_updates)
 contrib module is disabled by and it will also be disabled when it moves
 into Drupal core.
 
-### Drush
+## Drush
 
 Using `drush pm-install` or `drush pm-update` is disabled by default as part of
 the [amazeeio/drupal-integrations](https://github.com/amazeeio/drupal-integrations)

docs/drupal/first-deployment-of-drupal.md → docs/applications/drupal/first-deployment-of-drupal.md

@@ -4,7 +4,7 @@
 
 ## 1. Make sure you are all set
 
-In order to make your first deployment a successful one, please make sure that your [Drupal Project is Lagoonized](../using-lagoon-the-basics/setup-project.md) and you have set up the project in Lagoon. If not, don't worry! Follow the [Step-by-Step Guide](step-by-step-getting-drupal-ready-to-run-on-lagoon.md) which show you how this works.
+In order to make your first deployment a successful one, please make sure that your [Drupal Project is Lagoonized](../../using-lagoon-the-basics/setup-project.md) and you have set up the project in Lagoon. If not, don't worry! Follow the [Step-by-Step Guide](./step-by-step-getting-drupal-ready-to-run-on-lagoon.md) which show you how this works.
 
 ## 2. Push
 
@@ -19,13 +19,13 @@ git push
 
 This will trigger a push, and the Git hosting will inform Lagoon about this push via the configured webhook.
 
-If all is correct, you will see a notification in your configured chat system \(this is configured by your friendly Lagoon administrator\):
+If all is correct, you will see a notification in your configured chat system (this is configured by your friendly Lagoon administrator):
 
-![Slack notification of a deployment starting.](./first_deployment_slack_start.jpg)
+![Slack notification of a deployment starting.](../../images/first_deployment_slack_start.jpg)
 
-This tells you that Lagoon has just started to deploy your code. Depending on the size of the codebase and amount of containers, this will take a couple of seconds. Just relax. If you'd like to know what's happening now, check out the [Build and Deploy Process of Lagoon](../using-lagoon-the-basics/build-and-deploy-process.md).
+This tells you that Lagoon has just started to deploy your code. Depending on the size of the codebase and amount of containers, this will take a couple of seconds. Just relax. If you'd like to know what's happening now, check out the [Build and Deploy Process of Lagoon](../../concepts-basics/build-and-deploy-process.md).
 
-You can also check your Lagoon UI to see the progress of any deployment \(your Lagoon administrator has the info\).
+You can also check your Lagoon UI to see the progress of any deployment (your Lagoon administrator has the info).
 
 ## 3. A fail
 
@@ -85,9 +85,9 @@ git push
 
 This time all should be green:
 
-![Deployment Success!](./first_deployment_slack_success.jpg)
+![Deployment Success!](../../images/first_deployment_slack_success.jpg)
 
-Click on the links in the notification, and you should see your Drupal site loaded in all its beauty! It will probably not have images yet, which we will handle in [Step 6](first-deployment-of-drupal.md#6-synchronize-local-files-to-the-remote-lagoon-environment).
+Click on the links in the notification, and you should see your Drupal site loaded in all its beauty! It will probably not have images yet, which we will handle in [Step 6](./first-deployment-of-drupal.md#6-synchronize-local-files-to-the-remote-lagoon-environment).
 
 If it is still failing, check the logs link for more information.
 
@@ -121,7 +121,7 @@ The reason for that is that the Drupal cannot resolve the path of the files dire
 
 As soon as Lagoon is done building and deploying it will send a second notification to the chat system, like so:
 
-![Slack notification of complete deployment.](./first_deployment_slack_2nd_success.jpg)
+![Slack notification of complete deployment.](../../images/first_deployment_slack_2nd_success.jpg)
 
 This tells you:
 
@@ -136,7 +136,7 @@ That's it! We hope that wasn't too hard - making devOps accessible is what we ar
 
 That's the beauty of Lagoon: it's exactly the same: Push the branch name you defined to be your production branch and that one will be deployed.
 
-## Failure? Don't worry.
+## Failure? Don't worry
 
 Did the deployment fail? Oh no! But we're here to help:
 

docs/drupal/index.md → docs/applications/drupal/index.md

@@ -6,7 +6,7 @@ In this section you'll find more information on the various services that have b
 
 ## `drupal_integrations` Drupal scaffolding package
 
-The `drupal_integrations` package, available on [pacakagist](https://packagist.org/packages/amazeeio/drupal_integrations) extends Drupal's core-composer-scaffold for use on Lagoon. It also provides additional Drush command `drush la` to retreive the Drush aliases for your Lagoon project.
+The `drupal_integrations` package, available on [packagist](https://packagist.org/packages/amazeeio/drupal_integrations) extends Drupal's core-composer-scaffold for use on Lagoon. It also provides additional Drush command `drush la` to retreive the Drush aliases for your Lagoon project.
 
 ## `lagoon-logs` Drupal module
 

docs/drupal/phpunit-and-phpstorm.md → docs/applications/drupal/phpunit-and-phpstorm.md

@@ -5,7 +5,7 @@
 
       - You are using Docker.
 
-      - You are using a standard Amazee/Lagoon project with a [`docker-compose.yml`](../using-lagoon-the-basics/docker-compose-yml.md) file.
+      - You are using a standard Amazee/Lagoon project with a [`docker-compose.yml`](../../concepts-basics/docker-compose-yml.md) file.
 
       - You are on a Mac - it should work for other operating systems but folder structure and some configuration settings may be different.
 
@@ -25,7 +25,7 @@
 2. Click: `+`
 3. Select: `Docker for Mac`
 
-![Set Up Docker](./1-docker-setup.png)
+![Set Up Docker](../../images/1-docker-setup.png)
 
 ### Set Up CLI interpreter
 
@@ -43,7 +43,7 @@
    * Local path: `<ROOT_PATH>`
    * Remote path\*: `/app`
 
-![Add a new CLI interpreter:](./2-cli-interpreter.png)
+![Add a new CLI interpreter:](../../images/2-cli-interpreter.png)
 
 ### **Set Up Remote Interpreter**
 
@@ -58,7 +58,7 @@
    * Path to script\*: `/app/vendor/autoload.php`
    * Default configuration file\*: `/app/web/core/phpunit.xml`
 
-![Add Remote Interpreter](./3-remote-interpreter-setup.png)
+![Add Remote Interpreter](../../images/3-remote-interpreter-setup.png)
 
 #### Setup/Configure Runner Template <a id="Drupal:PHPUnitandPhpStorm-Setup/ConfigureRunnerTemplate"></a>
 
@@ -70,14 +70,14 @@
 
       2. Interpreter: `<CLI_INTERPRETER>`
 
-![Configure runner](./4-configure-runner.png)
+![Configure runner](../../images/4-configure-runner.png)
 
 !!! Note
       If you are not on a Mac, this may vary.
 
 ## Final checks
 
-### Some final checks to run before you run a test!
+### Some final checks to run before you run a test
 
 1. You have the project up and running:  `$ docker-compose up -d`
 2. The project is working without any errors, visit the site just to make sure it all works as expected - this is not 100% necessary, but nice to know it is working normally.
@@ -89,4 +89,4 @@ Now you have the above configuration set up it should be as straightforward as g
 
 Once you press this PhpStorm will use Docker to enter the CLI container, then start running PHPUnit based upon the config.
 
-![Here it is in action, look at it go!!](./5-going-green-1-.gif)
+![Here it is in action, look at it go!!](../../images/5-going-green-1-.gif)

docs/applications/drupal/services/README.md

@@ -0,0 +1,25 @@
+# Services
+
+## MariaDB is the open-source successor to MySQL
+
+[Learn about MariaDB with Drupal](mariadb.md)
+
+[Documentation on the plain MariaDB image](../../../docker-images/mariadb.md) (the MariaDB-Drupal image is built on this).
+
+## Redis is a fast, open-source, in-memory key-value data store for use as a database, cache, message broker, and queue
+
+[Learn about Redis with Drupal.](../services/redis.md)
+
+[Documentation on the Redis-persistent image.](../../../docker-images/redis.md)
+
+## Solr is an open-source search platform
+
+[Learn about Solr with Drupal.](../services/solr.md)
+
+[Documentation on the plain Solr image](../../../docker-images/solr.md) \(the Solr-Drupal image is built on this\).
+
+## Varnish is a powerful, open-source HTTP engine and reverse HTTP proxy that helps to speed up your website
+
+[Learn about Varnish with Drupal](../services/varnish.md)
+
+[Documentation on the plain Varnish image](../../../docker-images/varnish.md) \(the Varnish-Drupal image is built on this\).

docs/drupal/services/mariadb.md → docs/applications/drupal/services/mariadb.md

@@ -4,7 +4,7 @@ description: MariaDB is the open source successor to MySQL.
 
 # MariaDB-Drupal
 
-The Lagoon `mariadb-drupal` Docker image [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/mariadb-drupal/10.5.Dockerfile) is a customized [`mariadb`](../../docker-images/mariadb.md) image to use within Drupal projects in Lagoon. It differs from the `mariadb` image only for initial database setup, made by some environment variables:
+The Lagoon `mariadb-drupal` Docker image [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/mariadb-drupal/10.5.Dockerfile) is a customized [`mariadb`](../../../docker-images/mariadb.md) image to use within Drupal projects in Lagoon. It differs from the `mariadb` image only for initial database setup, made by some environment variables:
 
 | Environment Variable | Default | Description |
 | :--- | :--- | :--- |
@@ -14,7 +14,7 @@ The Lagoon `mariadb-drupal` Docker image [Dockerfile](https://github.com/uselago
 
 If the `LAGOON_ENVIRONMENT_TYPE` variable is set to `production`, performances are set accordingly by using `MARIADB_INNODB_BUFFER_POOL_SIZE=1024` and `MARIADB_INNODB_LOG_FILE_SIZE=256`.
 
-## Additional MariaDB [Logging](../../logging/logging.md)
+## Additional MariaDB [Logging](../../../logging/logging.md)
 
 During the course of development, it may be necessary to enable either query logging or slow query logging. To do so, set the environment variables `MARIADB_LOG_SLOW` or `MARIADB_LOG_QUERIES`. This can be done in `docker-compose.yml`.
 

docs/drupal/services/nginx.md → docs/applications/drupal/services/nginx.md

@@ -1,14 +1,14 @@
 # NGINX-Drupal
 
-The [Lagoon `nginx-drupal` Docker image](https://github.com/uselagoon/lagoon-images/blob/main/images/nginx-drupal/Dockerfile). Optimized to work with Drupal. Based on [Lagoon `nginx` image](../../docker-images/nginx.md).
+The [Lagoon `nginx-drupal` Docker image](https://github.com/uselagoon/lagoon-images/blob/main/images/nginx-drupal/Dockerfile). Optimized to work with Drupal. Based on [Lagoon `nginx` image](../../../docker-images/nginx.md).
 
 ## Lagoon adaptions
 
 This image is prepared to be used on Lagoon. There are therefore some things already done:
 
 * Folder permissions are automatically adapted with [`fix-permissions`](https://github.com/uselagoon/lagoon-images/blob/main/images/commons/fix-permissions), so this image will work with a random user.
 * To keep `drupal.conf` 's configuration file as clean and customizable as possible, we added `include` directives in the main sections of the file:`server`, `location /`, `location @drupal` and `location @php`.
-* Further information in the section [`Drupal.conf` customization](nginx.md#drupal-conf-customization).
+* Further information in the section [`Drupal.conf` customization](#drupalconf-customization).
 
 ## Included Drupal configuration \(`drupal.conf`\)
 

docs/drupal/services/php-cli.md → docs/applications/drupal/services/php-cli.md

@@ -1,6 +1,6 @@
 # PHP-CLI-Drupal
 
-The [Lagoon `php-cli-drupal` Docker image](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal) is optimized to work with Drupal. It is based on the [Lagoon `php-cli` image](../../docker-images/php-cli.md), and has all the command line tools needed for the daily maintenance of a Drupal website:
+The [Lagoon `php-cli-drupal` Docker image](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal) is optimized to work with Drupal. It is based on the [Lagoon `php-cli` image](../../../docker-images/php-cli.md), and has all the command line tools needed for the daily maintenance of a Drupal website:
 
 * `drush`
 * `drupal console`

docs/drupal/step-by-step-getting-drupal-ready-to-run-on-lagoon.md → docs/applications/drupal/step-by-step-getting-drupal-ready-to-run-on-lagoon.md

@@ -8,8 +8,8 @@ If you're working on a Drupal project, you can check out one of the various Drup
 
 Here is a summary of the Lagoon- and Drupal-specific files you will find:
 
-* `.lagoon.yml` - The main file that will be used by Lagoon to understand what should be deployed and many more things. This file has some sensible Drupal defaults. If you would like to edit or modify, please check the [documentation for `.lagoon.yml`](../using-lagoon-the-basics/lagoon-yml.md).
-* `docker-compose.yml`, `.dockerignore`, and `*.dockerfile` \(or `Dockerfile`\) - These files are used to run your local Drupal development environment, they tell Docker which services to start and how to build them. They contain sensible defaults and many commented lines. We hope that it's well-commented enough to be self-describing. If you would like to find out more, see [documentation for `docker-compose.yml`](../using-lagoon-the-basics/docker-compose-yml.md).
+* `.lagoon.yml` - The main file that will be used by Lagoon to understand what should be deployed and many more things. This file has some sensible Drupal defaults. If you would like to edit or modify, please check the [documentation for `.lagoon.yml`](../../concepts-basics/lagoon-yml.md).
+* `docker-compose.yml`, `.dockerignore`, and `*.dockerfile` \(or `Dockerfile`\) - These files are used to run your local Drupal development environment, they tell Docker which services to start and how to build them. They contain sensible defaults and many commented lines. We hope that it's well-commented enough to be self-describing. If you would like to find out more, see [documentation for `docker-compose.yml`](../../concepts-basics/docker-compose-yml.md).
 * `sites/default/*` - These `.php` and `.yml` files tell Drupal how to communicate with Lagoon containers both locally and in production. They also provide a straightforward system for specific overrides in development and production environments. Unlike other Drupal hosting systems, Lagoon never ever injects Drupal settings files into your Drupal. Therefore, you can edit them however you like. Like all other files, they contain sensible defaults and some commented parts.
 * `drush/aliases.drushrc.php` - These files are specific to Drush and tell Drush how to talk to the Lagoon GraphQL API in order to learn about all site aliases there are.
 * `drush/drushrc.php` - Some sensible defaults for Drush commands.
@@ -24,7 +24,7 @@ Drupal is shipped with `sites/*/settings*.php` and `sites/*/services*.yml` in `.
 
 Unfortunately the Drupal community has not decided on a standardized `WEBROOT` folder name. Some projects put Drupal within `web`, and others within `docroot` or somewhere else. The Lagoon Drupal settings files assume that your Drupal is within `web`, but if this is different for your Drupal, please adapt the files accordingly.
 
-### Note about composer.json
+### Note about `composer.json`
 
 If you installed Drupal via composer, please check your `composer.json` and make sure that the `name` is NOT `drupal/drupal`, as this could confuse Drush and other tools of the Drupal universe, just rename it to something like `myproject/drupal`
 

docs/applications/options.md

@@ -8,13 +8,13 @@ description: Configuring Applications for use on Lagoon
 
 Project- and environment-level configuration for Lagoon is provided in the `.lagoon.yml` file in your repository.
 
-See [`lagoon-yml.md`](../using-lagoon-the-basics/lagoon-yml.md).
+See [`lagoon-yml.md`](../concepts-basics/lagoon-yml.md).
 
 ## `docker-compose.yml`
 
 Service-level configuration for Lagoon in provided in the `docker-compose.yml` file in your repository. In particular, the `lagoon.type` and associated service labels are documented in the individual services.
 
-See [`docker-compose-yml.md`](../using-lagoon-the-basics/docker-compose-yml.md)
+See [`docker-compose-yml.md`](../concepts-basics/docker-compose-yml.md)
 
 ## Storage
 
@@ -47,4 +47,4 @@ Lagoon auto-generates routes for services that have ingress requirements. Custom
 
 Lagoon makes heavy use of environment variables, at build and runtime. Where these are used to provide critical configuration for your application (e.g. database config/credentials) - it is important that the local and Lagoon versions are named similarly.
 
-See [environment-variables.md](../using-lagoon-advanced/environment-variables.md).
+See [environment-variables.md](../concepts-advanced/environment-variables.md).