Glebaster/forum
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refactor and add a doc explaining how to deploy in prod

Browse Source
This commit is contained in:
Kévin Dunglas 2020-10-16 13:08:20 +02:00
parent cc03d09fa6
commit 88a7208acf
No known key found for this signature in database
GPG Key ID: 9D0C5D6EEB42C445
9 changed files with 191 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitattributes vendored
View File

@ -14,5 +14,3 @@ bin/console text eol=lf
*.ico binary
*.png binary
README.md export-ignore

106
README.md
View File

@ -6,9 +6,9 @@ A [Docker](https://www.docker.com/)-based installer and runtime for the [Symfony
## Getting Started
1. Run `docker-compose up` (the logs will be displayed in the current shell)
2. Open `https://localhost` in your favorite web browser and [accept the auto-generated TLS certificate](https://stackoverflow.com/a/15076602/1352334)
3. **Enjoy!**
1. If not already done, [install Docker Compose](https://docs.docker.com/compose/install/)
2. Run `docker-compose up` (the logs will be displayed in the current shell)
3. Open `https://localhost` in your favorite web browser and [accept the auto-generated TLS certificate](https://stackoverflow.com/a/15076602/1352334)
## Features
@ -19,101 +19,15 @@ A [Docker](https://www.docker.com/)-based installer and runtime for the [Symfony
* Just 2 services (PHP FPM and Caddy server)
* Super-readable configuration
## Selecting a Specific Symfony Version
**Enjoy!**
Use the `SYMFONY_VERSION` environment variable to select a specific Symfony version.
## Docs
For instance, use the following command to install Symfony 4.4:
$ SYMFONY_VERSION=4.4.* docker-compose up --build
To install a non-stable version of Symfony, use the `STABILITY` environment variable during the build.
The value must be [a valid Composer stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability)) .
For instance, use the following command to use the `master` branch of Symfony:
$ STABILITY=dev docker-compose up --build
## Customize Server Name
Use the `SERVER_NAME` environment variable to define your custom server name.
$ SERVER_NAME=symfony.wip docker-compose up --build
## Debugging
The default Docker stack is shipped without a Xdebug stage.
It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
### Add a Development Stage to the Dockerfile
To avoid deploying Symfony Docker to production with an active Xdebug extension,
it's recommended to add a custom stage to the end of the `Dockerfile`.
```Dockerfile
# Dockerfile
FROM symfony_php as symfony_php_dev
ARG XDEBUG_VERSION=2.9.8
RUN set -eux; \
apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
pecl install xdebug-$XDEBUG_VERSION; \
docker-php-ext-enable xdebug; \
apk del .build-deps
```
### Configure Xdebug with Docker Compose Override
Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yaml` ensures that the production
configuration remains untouched.
As example, an override could look like this:
```yaml
# docker-compose.debug.yaml
version: "3.4"
services:
php:
build:
context: .
target: symfony_php_dev
environment:
# See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
# See https://github.com/docker/for-linux/issues/264
# The `remote_host` below may optionally be replaced with `remote_connect_back`
XDEBUG_CONFIG: >-
remote_enable=1
remote_host=host.docker.internal
remote_port=9001
idekey=PHPSTORM
# This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
# Then PHPStorm will use the corresponding path mappings
PHP_IDE_CONFIG: serverName=symfony
```
Then run:
$ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
### Troubleshooting
Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.
$ docker-compose exec php php --version
PHP ...
with Xdebug v2.8.0 ...
### Editing Permissions on Linux
If you work on linux and cannot edit some of the project files right after the first installation, you can run `docker-compose run --rm php chown -R $(id -u):$(id -g) .` to set yourself as owner of the project files that were created by the docker container.
### Fix Chrome/Brave SSL
If you have a SSL trust issues, download the self-signed certificate and run :
$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/you/certificate.cer
1. [Build options](docs/build.md)
2. [Support for extra services](docs/extra-services.md)
3. [Deploying in production](docs/production.md)
4. [Installing Xdebug](docs/xdebug.md)
5. [Troubleshooting](docs/troubleshooting.md)
## Credits

22
docs/build.md Normal file
View File

@ -0,0 +1,22 @@
# Build Options
## Selecting a Specific Symfony Version
Use the `SYMFONY_VERSION` environment variable to select a specific Symfony version.
For instance, use the following command to install Symfony 4.4:
$ SYMFONY_VERSION=4.4.* docker-compose up --build
To install a non-stable version of Symfony, use the `STABILITY` environment variable during the build.
The value must be [a valid Composer stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability)) .
For instance, use the following command to use the `master` branch of Symfony:
$ STABILITY=dev docker-compose up --build
## Customizing the Server Name
Use the `SERVER_NAME` environment variable to define your custom server name.
$ SERVER_NAME=symfony.wip docker-compose up --build

BIN
docs/digitalocean-droplet.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 248 KiB

9
docs/extra-services.md Normal file
View File

@ -0,0 +1,9 @@
# Support for Extra Services
Symfony Docker is extensible. When you install a compatible Composer package using Symfony Flex,
the recipe will automatically modify the `Dockerfile` and `docker-compose.yml` to fulfill the requirements of this package.
The currently supported packages are:
* `symfony/orm-pack`: install a MariaDB service
* `symfony/messenger`: install a RabbitMQ service

BIN
docs/gandi-dns.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 139 KiB

75
docs/production.md Normal file
View File

@ -0,0 +1,75 @@
# Deploying in Production
Symfony Docker provides Docker images, and a Docker Compose definition optimized for production usage.
In this tutorial, we will learn how to deploy our Symfony application on a single server using Docker Compose.
## Preparing a Server
To deploy your application in production, you need a server.
In this tutorial we will use a virtual machine provided by DigitalOcean, but any Linux server can work.
If you already have a Linux server with Docker Compose installed, you can skip straight to [the next section](#configuring-a-domain-name).
Otherwise, use [this affiliate link](https://m.do.co/c/5d8aabe3ab80) to get $100 of free credit, create an account, then click on "Create a Droplet".
Then, click on the "Marketplace" tab under the "Choose an image" section and search for the app named "Docker".
This will provision an Ubuntu server with the latest versions of Docker and Docker Compose already installed!
To test, the cheapest plan will be enough, but for real production usage you'll probably want to pick a plan in the "general purpose" section that will fit your needs.
![Deploying a Symfony app on DigitalOcean with Docker Compose](digitalocean-droplet.png)
You can keep the defaults for other settings, or tweak them according to your needs.
Don't forget to add your SSH key or to create a password then press the "Finalize and create" button.
Then, wait a few seconds while your Droplet is provisioning.
When your Droplet is ready, use SSH to connect:
$ ssh root@<droplet-ip>
## Configuring a Domain Name
In most cases, you'll want to associate a domain name to your website.
If you don't own a domain name yet, you'll have to buy one through a registrar.
Use [this affiliate link](https://gandi.link/f/93650337) to redeem a 20% discount at Gandi.net.
Then create a DNS record of type `A` for your domain name pointing to the IP address of your server.
Example:
your-domain-name.example.com. IN A 207.154.233.113
Example in Gandi's UI:
![Creating a DNS record at Gandi.net](gandi-dns.png)
Note: Let's Encrypt, the service used by default by Symfony Docker to automatically generate a TLS certificate doesn't support using bare IP addresses.
Using a domain name if mandatory to use Let's Encrypt.
## Deploying
Copy your project on the server using `git clone`, `scp` or any other tool that may fit your need.
If you use GitHub, you may want to use [a deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys).
Deploy keys are also [supported by GitLab](https://docs.gitlab.com/ee/user/project/deploy_keys/).
Example with Git:
$ git clone git@github.com:<username>/<project-name>.git
Go into the directory containing your project (`<project-name>`), and start the app in production mode:
$ SERVER_NAME=your-domain-name.example.com docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
Be sure to replace `your-domain-name.example.com` by your actual domain name.
Your server is up and running, and a Let's Encrypt HTTPS certificate has been automatically generated for you.
Go to `https://your-domain-name.example.com` and enjoy!
## Disabling HTTPS
Alternatively, if you don't want to expose an HTTPS server but only an HTTP one, run the following command:
$ SERVER_NAME=:80 -f docker-compose.yml -f docker-compose.prod.yml up -d
## Deploying on Multiple Nodes
If you want to deploy your app on a cluster of machines, you can use [Docker Swarm](https://docs.docker.com/engine/swarm/stack-deploy/),
which is compatible with the provided Compose files.

11
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,11 @@
# Troubleshooting
## Editing Permissions on Linux
If you work on linux and cannot edit some of the project files right after the first installation, you can run `docker-compose run --rm php chown -R $(id -u):$(id -g) .` to set yourself as owner of the project files that were created by the docker container.
## Fix Chrome/Brave SSL
If you have a SSL trust issues, download the self-signed certificate and run :
$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/you/certificate.cer

64
docs/xdebug.md Normal file
View File

@ -0,0 +1,64 @@
# Installing Xdebug
The default Docker stack is shipped without a Xdebug stage.
It's easy though to add [Xdebug](https://xdebug.org/) to your project, for development purposes such as debugging tests or API requests remotely.
## Add a Debug Stage to the Dockerfile
To avoid deploying Symfony Docker to production with an active Xdebug extension,
it's recommended to add a custom stage to the end of the `Dockerfile`.
```Dockerfile
# Dockerfile
FROM symfony_php as symfony_php_debug
ARG XDEBUG_VERSION=2.9.8
RUN set -eux; \
apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
pecl install xdebug-$XDEBUG_VERSION; \
docker-php-ext-enable xdebug; \
apk del .build-deps
```
## Configure Xdebug with Docker Compose Override
Using an [override](https://docs.docker.com/compose/reference/overview/#specifying-multiple-compose-files) file named `docker-compose.debug.yaml` ensures that the production
configuration remains untouched.
As example, an override could look like this:
```yaml
# docker-compose.debug.yaml
version: "3.4"
services:
php:
build:
context: .
target: symfony_php_debug
environment:
# See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
# See https://github.com/docker/for-linux/issues/264
# The `remote_host` below may optionally be replaced with `remote_connect_back`
XDEBUG_CONFIG: >-
remote_enable=1
remote_host=host.docker.internal
remote_port=9001
idekey=PHPSTORM
# This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
# Then PHPStorm will use the corresponding path mappings
PHP_IDE_CONFIG: serverName=symfony
```
Then run:
$ docker-compose -f docker-compose.yml -f docker-compose.debug.yml up -d
## Troubleshooting
Inspect the installation with the following command. The requested Xdebug version should be displayed in the output.
$ docker-compose exec php php --version
PHP ...
with Xdebug v2.8.0 ...