Skip to content

Commit

Permalink
Merge pull request #2968 from uselagoon/mkdocs2
Browse files Browse the repository at this point in the history
  • Loading branch information
tobybellwood authored Dec 16, 2021
2 parents 8f41a67 + f82da29 commit 71e4899
Show file tree
Hide file tree
Showing 303 changed files with 1,435 additions and 2,660 deletions.
5 changes: 0 additions & 5 deletions .gitbook.yml

This file was deleted.

15 changes: 15 additions & 0 deletions .github/workflows/linkcheck.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
name: Check Markdown links
on:
push:
paths:
- 'docs/**'

jobs:
markdown-link-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
use-quiet-mode: 'yes'
folder-path: 'docs'
21 changes: 21 additions & 0 deletions .github/workflows/mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
name: Publish docs via GitHub Pages
on:
push:
branches:
- main
- mkdocs

jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v2

- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
# Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
env:
GITHUB_TOKEN: ${{ secrets.GH_ACTION_PAT }}
CONFIG_FILE: ./mkdocs.yml
Binary file removed docs/.gitbook/assets/0 (1).gif
Binary file not shown.
Binary file removed docs/.gitbook/assets/1-docker-setup (1).png
Binary file not shown.
Binary file removed docs/.gitbook/assets/2 (1).gif
Binary file not shown.
Binary file removed docs/.gitbook/assets/2-cli-interpreter (1).png
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file removed docs/.gitbook/assets/4-configure-runner (1).png
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file removed docs/.gitbook/assets/5-going-green-1- (1).gif
Binary file not shown.
Binary file not shown.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/bb_webhook_1 (1).png
Diff not rendered.
Binary file removed docs/.gitbook/assets/clamav_config.png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/gh_webhook_1 (1).png
Diff not rendered.
Binary file removed docs/.gitbook/assets/gh_webhook_2 (1).png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/gitlab_webhook (1).png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/lagoon-logo (1).png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/lagoon-logo (2).png
Diff not rendered.
Binary file removed docs/.gitbook/assets/lagoon-logo (3) (1).png
Diff not rendered.
Binary file removed docs/.gitbook/assets/lagoon-logo (3).png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Binary file removed docs/.gitbook/assets/step2_require (1).gif
Diff not rendered.
Binary file removed docs/.gitbook/assets/task-yarn-audit (1).png
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
Diff not rendered.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
1 change: 1 addition & 0 deletions docs/CNAME
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
docs.lagoon.sh
26 changes: 13 additions & 13 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,46 +1,45 @@
# Lagoon

![](<.gitbook/assets/lagoon-logo (3) (1).png>)
![](./lagoon-logo.png)

## Lagoon - Docker Build and Deploy System for OpenShift & Kubernetes
## Lagoon - Docker Build and Deploy System for Kubernetes

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?

* 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).
* 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.
2. When they are happy, they push the code to Git.
3. Lagoon parses the YAML files.
3. Lagoon parses the YAML files and adds in any additional needed configuration.
4. Lagoon builds the needed Docker images.
5. Lagoon creates the needed resources in OpenShift.
6. Lagoon pushes them to a Docker registry.
5. Lagoon pushes them to a Docker registry.
6. Lagoon creates the needed resources in Kubernetes.
7. Lagoon monitors the deployment of the containers.
8. When all is done, Lagoon informs the developers in different ways (Slack, email, website, etc.).
8. When all is done, Lagoon informs the developers in different ways \(Slack, email, website, etc.\).

## Help?

Questions? Ideas? Meet the maintainers and contributors.

Head to `#lagoon` in the amazee.io RocketChat: [https://amazeeio.rocket.chat](https://amazeeio.rocket.chat)
Head to `#lagoon` in the amazee.io RocketChat: [https://amazeeio.rocket.chat](https://amazeeio.rocket.chat/)

## A couple of things about Lagoon

1. **Lagoon is based on microservices**. The deployment and build workflow is very complex. We have multiple version control sources, multiple OpenShift servers, and multiple notification systems. Each deployment is unique and can take from seconds to hours. It's built with flexibility and robustness in mind. Microservices communicate through a messaging system, which allows us to scale individual services up and down. It allows us to survive down times of individual services. It also allows us to try out new parts of Lagoon in production without affecting others.
2. **Lagoon uses many programming languages**. Each programming language has specific strengths. We try to decide which language makes the most sense for each service. Currently, a lot of Lagoon is built in Node.js. This is partly because we started with Node.js, but also because Node.js allows asynchronous processing of webhooks, tasks and more. We are likely going to change the programming language of some services. This is what is great about microservices! We can replace a single service with another language without worrying about other parts of the platform.
3. **Lagoon is not Drupal-specific**. Everything has been built so that it can run any Docker image. There are existing Docker images for Drupal, and support for Drupal-specific tools like Drush. But that's it!
4. **Lagoon is DevOps**. It allows developers to define the services they need and customize them as they need. You might think this is not the right way to do it, and gives too much power to developers. We believe that as system engineers, we need to empower developers. If we allow developers to define services locally, and test them locally, they will find bugs and mistakes themselves.
5. **Lagoon runs on Docker and OpenShift.** (That one should be obvious, right?)
5. **Lagoon runs on Docker and Kubernetes.** \(That one should be obvious, right?\)
6. **Lagoon can be completely locally developed and tested.**
7. **Lagoon is completely integration tested**. This means we can test the whole process. From receiving Git webhooks to deploying into a Docker container, the same Git hash is deployed in OpenShift.
8. **Lagoon is built and deployed via Lagoon.** (Mind blown? 🤯 )
9. **Most important: It's a work in progress**. It's not done yet. At amazee.io, we believe that as a hosting community, we need to work together and share code where we can.
8. **Most important: It's a work in progress**. It's not done yet. At amazee.io, we believe that as a hosting community, we need to work together and share code where we can.

We want you to understand the Lagoon infrastructure and how the services work together. Here is a schema (it's a little out of date - it doesn't include some of the more recent services we've added, or cover Kubernetes, so we're working on an update!): [https://www.lucidchart.com/documents/view/a3cf0c4f-1bc1-438f-977d-4b26f235ceac](https://www.lucidchart.com/documents/view/a3cf0c4f-1bc1-438f-977d-4b26f235ceac)
We want you to understand the Lagoon infrastructure and how the services work together. Here is a schema \(it's a little out of date - it doesn't include some of the more recent services we've added, or cover Kubernetes, so we're working on an update!\): [https://www.lucidchart.com/documents/view/a3cf0c4f-1bc1-438f-977d-4b26f235ceac](https://www.lucidchart.com/documents/view/a3cf0c4f-1bc1-438f-977d-4b26f235ceac)

## History of Lagoon

Expand All @@ -56,4 +55,5 @@ At amazee.io, we believe in open source. It was always troubling for us that ope

### License

Lagoon is available under [`an Apache 2.0 License`](../LICENSE/).
Lagoon is available under [`an Apache 2.0 License`](https://github.com/uselagoon/lagoon/blob/main/LICENSE).

107 changes: 0 additions & 107 deletions docs/SUMMARY.md

This file was deleted.

17 changes: 0 additions & 17 deletions docs/_static/theme_overrides.css

This file was deleted.

4 changes: 2 additions & 2 deletions docs/administering-lagoon/create-project.gql
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ mutation {
}
) {
name
# TODO: Make a note of the openshift ID that comes back in the response
# TODO: Make a note of the Kubernetes ID that comes back in the response
id
}
}
Expand All @@ -33,7 +33,7 @@ mutation {
# This is the private key for a project, which is used to access the git code. If no private key is added, Lagoon will create a private key, which can later be accessed by loading the project.
privateKey: ""
# TODO: Fill in the openshift field
# This is the id of the OpenShift to assign to the project
# This is the id of the OpenShift or Kubernetes to assign to the project
openshift: 0
# TODO: Fill in the name field
# This is the project name
Expand Down
32 changes: 15 additions & 17 deletions docs/administering-lagoon/graphql-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

Direct API interactions in Lagoon are done via [GraphQL](graphql-queries.md).

In order to authenticate with the API, we need a JWT (JSON Web Token) that allows us to use the GraphQL API as admin. To generate this token, open the terminal of the `auto-idler` pod via the OpenShift UI and run the following command:
In order to authenticate with the API, we need a JWT \(JSON Web Token\) that allows us to use the GraphQL API as admin. To generate this token, open the terminal of the `auto-idler` pod via the OpenShift UI and run the following command:

```bash
./create_jwt.sh
Expand All @@ -25,11 +25,11 @@ To compose and send GraphQL queries, we recommend [GraphiQL.app](https://github.
Under "GraphQL Endpoint", enter the API endpoint URL with `/graphql` on the end. Then click on "Edit HTTP Headers" and add a new header:

* "Header name": `Authorization`
* "Header value": `Bearer [JWT token]` (make sure that the JWT token has no spaces, as this would not work)
* "Header value": `Bearer [JWT token]` \(make sure that the JWT token has no spaces, as this would not work\)

Press ESC to close the HTTP header overlay and now we are ready to send the first GraphQL request!

![Editing HTTP Headers in GraphiQL.](<../.gitbook/assets/graphiql-2020-01-29-18-05-54 (5) (5) (7) (1) (4) (1).png>)
![Editing HTTP Headers in GraphiQL.](./graphiql-2020-01-29-18-05-54.png)

Enter this in the left panel

Expand All @@ -41,24 +41,24 @@ query allProjects{
}
```

![Running a query in GraphiQL.](<../.gitbook/assets/graphiql-2020-01-29-20-10-32 (1).png>)
![Running a query in GraphiQL.](./graphiql-2020-01-29-20-10-32.png)

And press the ▶️ button (or press CTRL+ENTER).
And press the ▶️ button \(or press CTRL+ENTER\).

If all went well, your first GraphQL response should appear shortly afterwards in the right pane.

## Creating the first project

Let's create the first project for Lagoon to deploy! For this we'll use the queries from the GraphQL query template in [`create-project.gql`](create-project.gql).
Let's create the first project for Lagoon to deploy! For this we'll use the queries from the GraphQL query template in [`create-project.gql`](https://github.com/uselagoon/lagoon/blob/main/docs/administering-lagoon/create-project.gql).

For each of the queries (the blocks starting with `mutation {`), fill in all of the empty fields marked by TODO comments and run the queries in GraphiQL.app. This will create one of each of the following two objects:
For each of the queries \(the blocks starting with `mutation {`\), fill in all of the empty fields marked by TODO comments and run the queries in GraphiQL.app. This will create one of each of the following two objects:

1. `openshift` : The OpenShift cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own OpenShift, but also to any OpenShift anywhere in the world.
1. `openshift` : The OpenShift or Kubernetes cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own Kubernetes cluster, but also to any Kubernetes cluster anywhere in the world.
2. `project` : The Lagoon project to be deployed, which is a Git repository with a `.lagoon.yml` configuration file committed in the root.

## Allowing access to the project

In Lagoon, each developer authenticates via their SSH key(s). This determines their access to:
In Lagoon, each developer authenticates via their SSH key\(s\). This determines their access to:

1. The Lagoon API, where they can see and edit projects they have access to.
2. Remote shell access to containers that are running in projects they have access to.
Expand Down Expand Up @@ -219,9 +219,8 @@ Now for every deployment you will receive messages in your defined channel.
### Adding a new OpenShift target
{% hint style="info" %}
In Lagoon 1.x `addOpenshift` is used for both OpenShift and Kubernetes targets. In Lagoon 2.x this will change.
{% endhint %}
!!! Note "Note:"
In Lagoon 1.x `addOpenshift` is used for both OpenShift and Kubernetes targets. In Lagoon 2.x this will change.
The OpenShift cluster to which Lagoon should deploy. Lagoon is not only capable of deploying to its own OpenShift, but also to any OpenShift anywhere in the world.
Expand Down Expand Up @@ -288,7 +287,7 @@ mutation {
# This is the private key for a project, which is used to access the Git code.
privateKey: ""
# TODO: Fill in the OpenShift field.
# This is the id of the OpenShift to assign to the project.
# This is the id of the OpenShift or Kubernetes to assign to the project.
openshift: 0
# TODO: Fill in the name field.
# This is the project name.
Expand Down Expand Up @@ -412,9 +411,8 @@ mutation {
Update the production environment within a project:
{% hint style="warning" %}
This requires a redeploy in order for the changes to be reflected in the containers.
{% endhint %}
!!! warning "Warning:"
This requires a redeploy in order for the changes to be reflected in the containers.
```graphql
mutation {
Expand Down Expand Up @@ -524,7 +522,7 @@ mutation {
### Query for projects by metadata
Queries may be by `key` only (e.g return all projects where a specific key exists) or both `key` and `value` where both key and value must match.
Queries may be by `key` only \(e.g return all projects where a specific key exists\) or both `key` and `value` where both key and value must match.
All projects that have the `version` tag:
Expand Down
Loading

0 comments on commit 71e4899

Please sign in to comment.