Skip to content

Commit 6d20ecc

Browse files
author
Julien Neuhart
committed
Add Deployments documentation
1 parent a431b06 commit 6d20ecc

File tree

11 files changed

+251
-20
lines changed

11 files changed

+251
-20
lines changed

‎deployments/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
> Put here your deployments' guidelines (see [examples](examples)).
1+
> Put here your deployments' guidelines.

‎docs/docs/01_Get Started/1_Overview.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ a modern web application.
88

99
Many services compose this boilerplate.
1010

11-
## Application layer
11+
## Application Layer
1212

1313
This layer has two services:
1414

1515
1. The GraphQL API, built with [Symfony 5](https://symfony.com/), [TDBM](https://github.com/thecodingmachine/tdbm), and
1616
[GraphQLite](https://graphqlite.thecodingmachine.io/).
1717
2. The Web Application, built with [Nuxt.js](https://nuxtjs.org).
1818

19-
## Data layer
19+
## Data Layer
2020

2121
This layer has 3 services:
2222

@@ -30,10 +30,16 @@ This layer has 3 services:
3030

3131
:::
3232

33-
## Additional services
33+
## Additional Services
3434

3535
These services are mostly useful in development:
3636

3737
1. [Traefik](https://doc.traefik.io/traefik/), a reverse proxy.
3838
2. [MailHog](https://github.com/mailhog/MailHog), an email trapper with a web UI.
39-
3. phpMyAdmin, a web UI for displaying your database's data.
39+
3. phpMyAdmin, a web UI for displaying your database's data.
40+
41+
:::note
42+
43+
📣  In production, you may externalize them to the equivalent services from your provider.
44+
45+
:::

‎docs/docs/02_Development Environment/1_Docker Compose.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ in the *.env.dist* template.
7272
The existing services might not be enough for your use cases.
7373
You may therefore add new services to your *docker-compose.yml* file.
7474
75-
### Application layer
75+
### Application Layer
7676
7777
```yaml title="docker-compose.yml"
7878
services:
@@ -97,7 +97,7 @@ services:
9797
9898
:::
9999
100-
### Data layer
100+
### Data Layer
101101
102102
```yaml title="docker-compose.yml"
103103
services:
@@ -115,7 +115,7 @@ volumes:
115115
driver: local
116116
```
117117
118-
## Extend a Docker image
118+
## Extend a Docker Image
119119
120120
You might need to extend a Docker image for installing one or more packages.
121121

‎docs/docs/03_API/4_Housekeeping.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@ You should update to the latest minor/majors version whenever a new version is a
1515

1616
See [Symfony releases](https://symfony.com/releases).
1717

18-
## Minor versions
18+
## Minor Versions
1919

2020
See https://symfony.com/doc/current/setup/upgrade_minor.html.
2121

22-
## Major versions
22+
## Major Versions
2323

2424
See https://symfony.com/doc/current/setup/upgrade_major.html.
2525

‎docs/docs/16_Deployments/1_Overview.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
11
---
22
title: Overview
3-
slug: /deployments/overview
4-
---
3+
slug: /deployments
4+
---
5+
6+
In the [Get Started](/docs) chapter, we saw that many layers composes the Symfony Boilerplate:
7+
8+
1. Application Layer.
9+
2. Data Layer.
10+
3. Additional Services.
11+
12+
In remote environments, it is often not the developers that manage the last two layers.
13+
If that's the case, it would be best to externalize those services to the equivalents from your provider.
14+
15+
In this chapter, we focus on how to deliver properly the first layer.

‎docs/docs/16_Deployments/2_CICD.md‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/docs/16_Deployments/2_Docker Images.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Docker Images
3+
slug: /deployments/docker-images
4+
---
5+
6+
The Symfony Boilerplate provides two Dockerfiles:
7+
8+
* *src/api/Dockerfile*.
9+
* *src/webapp/Dockerfile*.
10+
11+
They contain all the instructions required for building the API and web application Docker images.
12+
13+
All you need to do is to provide a distinct `.env` file for each of them (at the root of the Dockerfiles directories).
14+
Their content will differ according to your remote environments.
15+
16+
You should create these `.env` files in your CI/CD processes, and never commit their content in your Git repository.
17+
Prefer secrets from your CI/CD provider! 😉
18+
19+
These `.env` files should contain:
20+
21+
1. **API:** the environment variables for configuring Symfony.
22+
2. **Web application:** the environment variables for configuring Nuxt.js.
23+
24+
:::note
25+
26+
📣  You may take a look at your development *docker-compose.yml* file for the list of environment variables.
27+
28+
:::
29+

‎docs/docs/16_Deployments/3_CICD.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: CI/CD
3+
slug: /deployments/cicd
4+
---
5+
6+
## GitLab CI
7+
8+
```yaml title=".gitlab-ci.yml"
9+
stages:
10+
- tests
11+
- build_push_docker_images
12+
13+
# ------------------------------------------
14+
# TESTS
15+
# ------------------------------------------
16+
17+
api_tests:
18+
stage: tests
19+
image: thecodingmachine/php:7.4-v3-apache
20+
services:
21+
- name: mysql:8.0
22+
command: ["--default-authentication-plugin=mysql_native_password"]
23+
variables:
24+
# Docker PHP image.
25+
# ---------------------
26+
APACHE_DOCUMENT_ROOT: "public/"
27+
PHP_EXTENSION_XDEBUG: "1"
28+
PHP_EXTENSION_REDIS: "1"
29+
PHP_EXTENSION_INTL: "1"
30+
PHP_EXTENSION_GD: "1"
31+
PHP_INI_MEMORY_LIMIT: "1G"
32+
# Docker MySQL image.
33+
# Make sure the values are matching
34+
# the corresponding values from SYMFONY_ENV_CONTENT.
35+
# ---------------------
36+
MYSQL_ROOT_PASSWORD: "foo"
37+
MYSQL_DATABASE: "foo"
38+
MYSQL_USER: "foo"
39+
MYSQL_PASSWORD: "foo"
40+
# Symfony.
41+
# ---------------------
42+
SYMFONY_ENV_CONTENT: "$SYMFONY_ENV_CONTENT_TESTS" # .env file content for tests (from GitLab CI/CD variables).
43+
before_script:
44+
- cd src/api
45+
- echo "$SYMFONY_ENV_CONTENT" > .env
46+
script:
47+
- composer install
48+
- composer dump-env test
49+
# Static analysis.
50+
- composer cscheck
51+
- composer phpstan
52+
- composer deptrac
53+
- composer yaml-lint
54+
# Integration tests.
55+
- composer pest
56+
57+
webapp_tests:
58+
stage: tests
59+
image: thecodingmachine/nodejs:12
60+
before_script:
61+
- cd src/webapp
62+
script:
63+
- yarn
64+
# Static analysis.
65+
- yarn lint
66+
67+
# ------------------------------------------
68+
# BUILD PUSH DOCKER IMAGES
69+
# ------------------------------------------
70+
71+
.api_build_push_docker_image:
72+
stage: build_push_docker_images
73+
image: docker:git
74+
services:
75+
- docker:dind
76+
variables:
77+
DOCKER_DRIVER: "overlay2"
78+
SYMFONY_ENV_CONTENT: "foo"
79+
ENV_NAME: "foo"
80+
before_script:
81+
- cd src/api
82+
script:
83+
- echo "$SYMFONY_ENV_CONTENT" > .env
84+
- docker login -u gitlab-ci-token -p "$CI_BUILD_TOKEN" registry.example.com
85+
- docker build -t "registry.example.com/group/project/api-$ENV_NAME:$CI_COMMIT_REF_SLUG" .
86+
- docker push "registry.example.com/group/project/api-$ENV_NAME:$CI_COMMIT_REF_SLUG"
87+
only:
88+
- tags
89+
90+
api_build_push_docker_image_testing:
91+
extends: .api_build_push_docker_image
92+
variables:
93+
SYMFONY_ENV_CONTENT: "$SYMFONY_ENV_CONTENT_TESTING" # .env file content for testing (from GitLab CI/CD variables).
94+
ENV_NAME: "testing"
95+
96+
api_build_push_docker_image_staging:
97+
extends: .api_build_push_docker_image
98+
variables:
99+
SYMFONY_ENV_CONTENT: "$SYMFONY_ENV_CONTENT_STAGING" # .env file content for staging (from GitLab CI/CD variables).
100+
ENV_NAME: "staging"
101+
102+
api_build_push_docker_image_prod:
103+
extends: .api_build_push_docker_image
104+
variables:
105+
SYMFONY_ENV_CONTENT: "$SYMFONY_ENV_CONTENT_PROD" # .env file content for prod (from GitLab CI/CD variables).
106+
ENV_NAME: "prod"
107+
108+
.webapp_build_push_docker_image:
109+
stage: build_push_docker_images
110+
image: docker:git
111+
services:
112+
- docker:dind
113+
variables:
114+
DOCKER_DRIVER: "overlay2"
115+
NUXTJS_ENV_CONTENT: "foo"
116+
ENV_NAME: "foo"
117+
before_script:
118+
- cd src/webapp
119+
script:
120+
- echo "$NUXTJS_ENV_CONTENT" > .env
121+
- docker login -u gitlab-ci-token -p "$CI_BUILD_TOKEN" registry.example.com
122+
- docker build -t "registry.example.com/group/project/webapp-$ENV_NAME:$CI_COMMIT_REF_SLUG" .
123+
- docker push "registry.example.com/group/project/webapp-$ENV_NAME:$CI_COMMIT_REF_SLUG"
124+
only:
125+
- tags
126+
127+
webapp_build_push_docker_image_testing:
128+
extends: .webapp_build_push_docker_image
129+
variables:
130+
NUXTJS_ENV_CONTENT: "$NUXTJS_ENV_CONTENT_TESTING" # .env file content for testing (from GitLab CI/CD variables).
131+
ENV_NAME: "testing"
132+
133+
webapp_build_push_docker_image_staging:
134+
extends: .webapp_build_push_docker_image
135+
variables:
136+
NUXTJS_ENV_CONTENT: "$NUXTJS_ENV_CONTENT_STAGING" # .env file content for staging (from GitLab CI/CD variables).
137+
ENV_NAME: "staging"
138+
139+
webapp_build_push_docker_image_prod:
140+
extends: .webapp_build_push_docker_image
141+
variables:
142+
NUXTJS_ENV_CONTENT: "$NUXTJS_ENV_CONTENT_PROD" # .env file content for prod (from GitLab CI/CD variables).
143+
ENV_NAME: "prod"
144+
```

‎docs/docs/16_Deployments/3_LogRocket.md‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/docs/16_Deployments/4_Run.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Run
3+
slug: /deployments/run
4+
---
5+
6+
## API
7+
8+
In your remote environments, you will have two kind of instances:
9+
10+
1. A GraphQL API.
11+
2. A consumer of messages from Redis (emails and asynchronous tasks).
12+
13+
For instance, if you use Docker Compose:
14+
15+
```yaml title="docker-compose.yml"
16+
services:
17+
18+
api:
19+
image: api_docker_image:docker_image_tag
20+
21+
# Consumer for asynchronous tasks and emails.
22+
api_consumer:
23+
image: api_docker_image:docker_image_tag
24+
# The command to launch instead of the default one.
25+
command: php bin/console messenger:consume async
26+
```
27+
28+
The API being stateless, you may also scale it without worries.
29+
30+
## Web Application
31+
32+
The Web Application being stateless, you may scale it without worries.

0 commit comments

Comments
 (0)