Skip to content

Commit

Permalink
docs: documentation and dockerfile changes
Browse files Browse the repository at this point in the history
  • Loading branch information
tobybellwood committed Jul 6, 2024
1 parent 74d4ecd commit 98491ef
Show file tree
Hide file tree
Showing 78 changed files with 244 additions and 256 deletions.
12 changes: 5 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,9 @@ Lagoon can be installed:
- Locally (for evaluation, testing, debugging or development) using [Helm](https://helm.sh/) charts and [kind](https://kind.sigs.k8s.io/), [microk8s](https://microk8s.io/), [k3s](https://k3s.io/) or similar.
- Into your managed Kubernetes cloud provider of choice - it's running in production on [Amazon Elastic Kubernetes Service](https://aws.amazon.com/eks/), [Azure Kubernetes Service](https://azure.microsoft.com/en-au/services/kubernetes-service/), and [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), but we are confident that it will also run on any other managed Kubernetes service.

For more information on developing or contributing to Lagoon, head to https://docs.lagoon.sh/contributing-to-lagoon
For more information on developing or contributing to Lagoon, head to https://docs.lagoon.sh/contributing

For more information on installing and administering Lagoon, head to https://docs.lagoon.sh/administering-lagoon
For more information on installing and administering Lagoon, head to https://docs.lagoon.sh/installing-lagoon/requirements/

### Architecture

Expand Down Expand Up @@ -76,7 +76,7 @@ All the services that are used to provision, deploy and maintain sites hosted by
- [Storage Calculator](https://github.com/uselagoon/storage-calculator) (an optional service to collect the size of storage and databases)
- [Remote Controller](https://github.com/uselagoon/remote-controller) (the controllers that handle building and deploying sites onto Lagoon)
- [Build Deploy Tool](https://github.com/uselagoon/build-deploy-tool) (the service that computes which services, configuration and settings to provision for Kubernetes)
- [Aergia](https://github.com/amazeeio/aergia-controller) (an optional controller that can idle non-production sites not currently in use to conserve resources)
- [Aergia](https://github.com/uselagoon/aergia-controller) (an optional controller that can idle non-production sites not currently in use to conserve resources)
- [Dioscuri](https://github.com/amazeeio/dioscuri) (an optional operator that provides Active/Standby functionality to Lagoon)
- [DBaaS Operator](https://github.com/amazeeio/dbaas-operator) (an optional operator that provisions databases from an underlying managed database)

Expand All @@ -86,7 +86,7 @@ All the services that are used to provision, deploy and maintain sites hosted by
### Lagoon Tools
- [lagoon-cli](https://github.com/uselagoon/lagoon-cli) (the command-line interface for managing sites on Lagoon)
- [lagoon-sync](https://github.com/uselagoon/lagoon-sync) (a command-line interface for syncing databases or file assets between Lagoon environments)
- [drush-alias](https://github.com/uselagoon/lagoon/tree/main/services/drush-alias) (provides Drupal developers with an automated alias service for Drush)
- [drush-alias](https://github.com/uselagoon/lagoon-service-images/tree/main/drush-alias) (provides Drupal developers with an automated alias service for Drush)

### Additional Services

Expand All @@ -98,7 +98,7 @@ These services are usually installed alongside either Lagoon Core or Lagoon Remo
- [k8up](https://k8up.io/) (provides a scheduled backup and prune service to environment namespaces)
- Lagoon Logging (optional)
- [lagoon-logging](https://github.com/uselagoon/lagoon-charts/tree/main/charts/lagoon-logging) (utilizes [banzaicloud/logging-operator](https://github.com/banzaicloud/logging-operator) to collect and augment container&router logs from all sites, and sends them to a logs-dispatcher)
- [logs-dispatcher](https://github.com/uselagoon/lagoon/tree/main/services/logs-dispatcher) (collects application logs from sites, as well as container&router logs from lagoon-logging, enriches them with additional metadata and sends them to a central log concentrator)
- [logs-dispatcher](https://github.com/uselagoon/lagoon-service-images/tree/main/logs-dispatcher) (collects application logs from sites, as well as container&router logs from lagoon-logging, enriches them with additional metadata and sends them to a central log concentrator)
- [lagoon-logs-concentrator](https://github.com/uselagoon/lagoon-charts/tree/main/charts/lagoon-logs-concentrator) (collects logs from remote logs-dispatchers and sends them to Elasticsearch)
- Elasticsearch or Opensearch (optional)
- [OpenSearch](https://opensearch.org/docs/latest/opensearch/index/) (provides centralized log storage, search and analysis)
Expand All @@ -109,8 +109,6 @@ These services are usually installed alongside either Lagoon Core or Lagoon Remo
- PostgreSQL (self managed or via [Amazon RDS for PostgreSQL](https://aws.amazon.com/rds/postgresql/), [Amazon Aurora PostgreSQL](https://aws.amazon.com/rds/aurora/postgresql-features/), [Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql), [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/docs/postgres) )
- MongoDB (self managed, or via [Amazon DocumentDB](https://aws.amazon.com/documentdb/), [Azure Cosmos DB](https://azure.microsoft.com/en-au/services/cosmos-db/) )
- Open Policy Agent (optional)
- [lagoon-gatekeeper](https://github.com/uselagoon/lagoon-charts/tree/main/charts/lagoon-gatekeeper) (centralized policy library for Lagoon)


## Testing

Expand Down
5 changes: 1 addition & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ and for a deeper understanding, [Lagoon Concepts - Advanced](concepts-advanced/i

If you want to develop Lagoon \(add features, fix bugs\), [Developing Lagoon](contributing-to-lagoon/developing-lagoon.md)


## TL;DR: How Lagoon Works

1. Developers define and configure needed services within YAML files.
Expand All @@ -37,9 +36,7 @@ If you want to develop Lagoon \(add features, fix bugs\), [Developing Lagoon](co

Questions? Ideas? Meet the maintainers and contributors.

Chat with us on the Lagoon Discord: [https://discord.gg/te5hHe95JE
](https://discord.gg/te5hHe95JE
)
Chat with us on the Lagoon Discord: [https://discord.gg/te5hHe95JE](https://discord.gg/te5hHe95JE)

## A couple of things about Lagoon

Expand Down
2 changes: 1 addition & 1 deletion docs/applications/drupal/first-deployment-of-drupal.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ With full Drush site alias support in Lagoon, you can synchronize a local databa
!!! warning
You may have to tell pygmy about your public keys before the next step.

If you get an error like `Permission denied (publickey)`, check out the documentation here: [pygmy - adding ssh keys](https://pygmy.readthedocs.io/en/master/ssh_agent).
If you get an error like `Permission denied (publickey)`, check out the documentation here: [pygmy - adding ssh keys](https://pygmystack.github.io/pygmy/ssh_agent/).

First let's make sure that you can see the Drush site aliases:

Expand Down
6 changes: 4 additions & 2 deletions docs/applications/drupal/services/php-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,11 @@ The [Lagoon `php-cli-drupal` Docker image](https://github.com/uselagoon/lagoon-i
## Supported versions

* 7.3 \(available for compatibility only, no longer officially supported\)
* 7.4 [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal/7.4.Dockerfile) - `uselagoon/php-7.4-cli-drupal`
* 8.0 [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal/8.0.Dockerfile) - `uselagoon/php-8.0-cli-drupal`
* 7.4 \(available for compatibility only, no longer officially supported\) - `uselagoon/php-7.4-cli-drupal`
* 8.0 \(available for compatibility only, no longer officially supported\) - `uselagoon/php-8.0-cli-drupal`
* 8.1 [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal/8.1.Dockerfile) - `uselagoon/php-8.1-cli-drupal`
* 8.2 [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal/8.2.Dockerfile) - `uselagoon/php-8.2-cli-drupal`
* 8.3 [Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/php-cli-drupal/8.3.Dockerfile) - `uselagoon/php-8.3-cli-drupal`

All PHP versions use their own Dockerfiles.

Expand Down
20 changes: 7 additions & 13 deletions docs/applications/drupal/services/solr.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

## Standard use

For Solr 5.5, 6.6 and 7.7, we ship the default schema files provided by the [search\_api\_solr](https://www.drupal.org/project/search_api_solr) Drupal module. Add the Solr version you would like to use in your `docker-compose.yml` file, following [our example](https://github.com/amazeeio/drupal-example-simple/blob/63b3fc613260d5192b7e2dd0167c6fc85d8d9162/docker-compose.yml#L110).
For Solr 8 and 9, we ship the default schema files provided by the [search\_api\_solr](https://www.drupal.org/project/search_api_solr) Drupal module. Add the Solr version you would like to use in your `docker-compose.yml` file, following [our example](https://github.com/lagoon-examples/drupal-solr).

## Custom schema

To implement schema customizations for Solr in your project, look to how Lagoon [creates our standard images](https://github.com/uselagoon/lagoon-images/blob/main/images/solr-drupal/7.7.Dockerfile).
To implement schema customizations for Solr in your project, look to how Lagoon [creates our standard images](https://github.com/uselagoon/lagoon-images/blob/main/images/solr-drupal/8.Dockerfile).

* In the `solr` section of your `docker-compose.yml` file, replace `image: amazeeio/solr:7.7` with:
* In the `solr` section of your `docker-compose.yml` file, replace `image: uselagoon/solr:8` with:

```yaml title="docker-compose.yml"
build:
Expand All @@ -20,13 +20,11 @@ To implement schema customizations for Solr in your project, look to how Lagoon
* Create a `solr.dockerfile`.

```bash title="solr.dockerfile"
FROM amazeeio/solr:7.7
FROM uselagoon/solr:8
COPY .lagoon/solr /solr-conf/conf
RUN precreate-core drupal /solr-conf
CMD ["solr-foreground"]
CMD solr-recreate drupal /solr-conf && solr-foreground
```

The goal is to have your Solr configuration files exist at `/solr-conf/conf` in the image you are building.
Expand All @@ -36,11 +34,7 @@ The goal is to have your Solr configuration files exist at `/solr-conf/conf` in
To implement multiple cores, you will also need to ship your own Solr schema as above. The only change needed is to the `CMD` of the Dockerfile - repeat the pattern of `precreate-core corename /solr-conf/ ;` for each core you require.

```bash title="solr.dockerfile"
FROM amazeeio/solr:7.7-drupal
RUN precreate-core drupal-index1 /solr-conf && \
precreate-core drupal-index2 /solr-conf && \
precreate-core drupal-index3 /solr-conf
FROM uselagoon/solr:8-drupal
CMD ["solr-foreground"]
CMD solr-recreate drupal /solr-conf && solr-recreate more-drupal /solr-conf && solr-foreground
```
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Site path : sites/default
!!! warning
You may have to tell pygmy about your public key before the next step.

If you get an error like `Permission denied (publickey)`, check out the documentation here: [pygmy - adding ssh keys](https://pygmy.readthedocs.io/en/master/ssh_agent)
If you get an error like `Permission denied (publickey)`, check out the documentation here: [pygmy - adding ssh keys](https://pygmystack.github.io/pygmy/ssh_agent/)

Now it is time to install Drupal \(if instead you would like to import an existing SQL file, please [skip to step 7](step-by-step-getting-drupal-ready-to-run-on-lagoon.md#7-import-existing-database-dump), but we suggest you start with a clean Drupal installation in the beginning to be sure everything works\).

Expand Down
2 changes: 1 addition & 1 deletion docs/applications/other.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Extending on, or inheriting from the [commons image](../docker-images/commons.md
This brief example shows how to build a Hugo website and serve it as static files in an NGINX image. The commons image is used to add Hugo, copy the site in, and build it. The NGINX image is then used to serve the site, with the addition of a customized NGINX config.

```bash title="nginx.dockerfile"
FROM uselagoon/commons as builder
FROM uselagoon/commons AS builder

RUN apk add hugo git
WORKDIR /app
Expand Down
2 changes: 1 addition & 1 deletion docs/applications/ruby.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ In our Rails example, we're importing the `logstash-logger` gem, and then in our

## Database configuration

The example uses our PostgreSQL image (see the `docker-compose.yml` file). Configuring database access in Rails for Lagoon is very straightforward. Since Lagoon injects the database host, name, and credentials as environment variables, we can change our [`config/database.yml`](https://github.com/lagoon-examples/ruby-on-rails/blob/main/config/database.yml) to be aware of these env vars, and consume them if they exist.
The example uses our PostgreSQL image (see the `docker-compose.yml` file). Configuring database access in Rails for Lagoon is very straightforward. Since Lagoon injects the database host, name, and credentials as environment variables, we can change our [`config/database.yml`](https://github.com/lagoon-examples/ruby-on-rails-demo/blob/main/config/database.yml.yml) to be aware of these env vars, and consume them if they exist.

```yaml title="config/database.yml"
default: &default
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts-advanced/environment-idling.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## What is the Environment Idler?

Lagoon can utilize the [Aergia controller](https://github.com/amazeeio/aergia-controller), (installed in the `lagoon-remote`) to automatically idle environments if they have been unused for a defined period of time. This is done in order to reduce the load on the Kubernetes clusters and improve the overall performance of production environments and development environments that are actually in use.
Lagoon can utilize the [Aergia controller](https://github.com/uselagoon/aergia-controller), (installed in the `lagoon-remote`) to automatically idle environments if they have been unused for a defined period of time. This is done in order to reduce the load on the Kubernetes clusters and improve the overall performance of production environments and development environments that are actually in use.

### How does an environment get idled?

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts-basics/docker-compose-yml.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ services:
lagoon.persistent: /app/web/sites/default/files/

mariadb:
image: amazeeio/mariadb-drupal
image: uselagoon/mariadb-10.11-drupal
labels:
lagoon.type: mariadb
```
Expand Down
2 changes: 1 addition & 1 deletion docs/docker-images/redis.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ It differs from `redis` only with the `FLAVOR` environment variable, which will

## Troubleshooting

The Lagoon Redis images all come pre-loaded with the `redis-cli` command, which allows for querying the Redis service for information and setting config values dynamically. To use this utility, you can simply SSH into your Redis pod by using the instructions [here] (../interacting/ssh.md) with `redis` as the `pod` value then run it from the terminal once you've connected.
The Lagoon Redis images all come pre-loaded with the `redis-cli` command, which allows for querying the Redis service for information and setting config values dynamically. To use this utility, you can simply SSH into your Redis pod by using the instructions [here](../interacting/ssh.md) with `redis` as the `pod` value then run it from the terminal once you've connected.

### Maximum Memory Policy

Expand Down
2 changes: 1 addition & 1 deletion docs/docker-images/solr.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Solr

The [Lagoon `Solr` image Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/solr/7.Dockerfile). Based on the official [`solr:<version>-alpine` images](https://hub.docker.com/_/solr).
The [Lagoon `Solr` image Dockerfile](https://github.com/uselagoon/lagoon-images/blob/main/images/solr/8.Dockerfile). Based on the official [`solr:<version>-alpine` images](https://hub.docker.com/_/solr).

This Dockerfile is intended to be used to set up a standalone Solr server with an initial core `mycore`.

Expand Down
2 changes: 1 addition & 1 deletion docs/installing-lagoon/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ We recommend installing a Harbor version greater than [2.6.0](https://github.com

### k8up for backups

Lagoon has built in configuration for the [K8up](https://k8up.io/k8up/1.2/index.html) backup operator. Lagoon can configure prebackup pods, schedules and retentions, and manage backups and restores for K8up. Lagoon currently only supports the 1.x versions of K8up, owing to a namespace change in v2 onwards, but we are working on a fix.
Lagoon has built in configuration for the [K8up](https://docs.k8up.io/k8up/1.2/index.html) backup operator. Lagoon can configure prebackup pods, schedules and retentions, and manage backups and restores for K8up. Lagoon currently only supports the 1.x versions of K8up, owing to a namespace change in v2 onwards, but we are working on a fix.

!!! bug "K8up v2:"
Lagoon does not currently support K8up v2 onwards due to a namespace change [here](https://github.com/uselagoon/build-deploy-tool/issues/121).
Expand Down
2 changes: 1 addition & 1 deletion docs/interacting/graphql-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ query {
### Updating objects
The Lagoon GraphQL API can not only display objects and create objects, it also has the capability to update existing objects, using [a patch object](https://blog.apollographql.com/designing-graphql-mutations-e09de826ed97).
The Lagoon GraphQL API can not only display objects and create objects, it also has the capability to update existing objects, using [a patch object](https://www.apollographql.com/blog/designing-graphql-mutations).
Update the branches to deploy within a project:
Expand Down
7 changes: 7 additions & 0 deletions docs/ja/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,14 @@ Lagoonの仕組みを理解するためには、[Lagoonの概念 - 基本](conce
7. Lagoon はコンテナの展開を監視します。
8. すべてが完了すると、Lagoon はさまざまな方法 (Slack、メール、Web サイトなど) で開発者に通知します。

## ヘルプが必要ですか?

質問がありますか? アイデアがありますか? メンテナーや貢献者に会ってください。

Lagoon Discord でチャットしましょう: [https://discord.gg/te5hHe95JE](https://discord.gg/te5hHe95JE)

## Lagoonについて { #a-couple-of-things-about-lagoon }

1. **Lagoon はマイクロサービスに基づいています**。デプロイメントとビルドのワークフローは非常に複雑です。複数のバージョン管理ソース、複数のクラスター、複数の通知システムがあります。各デプロイメントは一意であり、数秒から数時間かかる場合があります。柔軟性と堅牢性を考慮して構築されています。マイクロサービスはメッセージング システムを介して通信するため、個々のサービスをスケールアップおよびスケールダウンできます。これにより、個々のサービスのダウンタイムを乗り切ることができます。また、他の部分に影響を与えることなく、本番環境で Lagoon の新しい部分を試すこともできます。
2. **Lagoon では多くのプログラミング言語が使用されています**。各プログラミング言語にはそれぞれ固有の長所があります。私たちは、各サービスに最も適した言語を決定するよう努めています。現在、Lagoon の多くは Node.js で構築されています。これは最初にNode.jsを使い始めたからだけでなく、Node.jsがwebhooks、タスクなどの非同期処理を可能にするからです。一部のサービスのプログラミング言語を変更することを考えています。これがマイクロサービスの素晴らしいところです!他のプラットフォームの部分を心配することなく、一つのサービスを別の言語で置き換えることができます。
3. **LagoonはDrupal特有のものではありません**。すべてが任意のDockerイメージを実行できるように構築されています。Drupal用の既存のDockerイメージがあり、DrushのようなDrupal特有のツールもサポートしています。しかし、それだけです!
Expand Down
4 changes: 2 additions & 2 deletions docs/ja/applications/drupal/automatic-updates.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ Lagoonは、Drupalコアやcontribの一部の更新方法と互換性のない

## Drupal 自動更新

[自動更新] (https ://www.drupal.org/project/automatic_updates)
[自動更新](https ://www.drupal.org/project/automatic_updates)
contribモジュールは無効化されており、Drupal coreに移行する際も無効化されます。

## Drush

`drush pm-install`または`drush pm-update`は、デフォルトで無効化されています。これは[amazeeio/drupal-integrations](https://github.com/amazeeio/drupal-integrations)
パッケージの一部としてです。
パッケージの一部としてです。
Loading

0 comments on commit 98491ef

Please sign in to comment.