diff --git a/.gitattributes b/.gitattributes index 86fc82d..590d686 100644 --- a/.gitattributes +++ b/.gitattributes @@ -14,5 +14,3 @@ bin/console text eol=lf *.ico binary *.png binary - -README.md export-ignore diff --git a/README.md b/README.md index ea6f4da..d9e612a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..23aa09d --- /dev/null +++ b/docs/build.md @@ -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 diff --git a/docs/digitalocean-droplet.png b/docs/digitalocean-droplet.png new file mode 100644 index 0000000..65f19aa Binary files /dev/null and b/docs/digitalocean-droplet.png differ diff --git a/docs/extra-services.md b/docs/extra-services.md new file mode 100644 index 0000000..594c820 --- /dev/null +++ b/docs/extra-services.md @@ -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 diff --git a/docs/gandi-dns.png b/docs/gandi-dns.png new file mode 100644 index 0000000..b2a2377 Binary files /dev/null and b/docs/gandi-dns.png differ diff --git a/docs/production.md b/docs/production.md new file mode 100644 index 0000000..3308733 --- /dev/null +++ b/docs/production.md @@ -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@ + +## 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:/.git + +Go into the directory containing your project (``), 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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..708a66a --- /dev/null +++ b/docs/troubleshooting.md @@ -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 diff --git a/docs/xdebug.md b/docs/xdebug.md new file mode 100644 index 0000000..f0e3b95 --- /dev/null +++ b/docs/xdebug.md @@ -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 ...