WIP: website

Author: Julien Neuhart

README.md

@@ -1,4 +1,6 @@
-**Caution:** this is still work in progress.
+This is a template of a *README*.
+
+Official documentation: https://thecodingmachine.github.io/symfony-boilerplate
 
 ---
 
@@ -22,7 +24,7 @@ Install the latest version of [Docker](https://docs.docker.com/install/) and
 We strongly recommend installing [Vagrant](https://www.vagrantup.com/) and 
 [VirtualBox](https://www.virtualbox.org/).
 
-Indeed, Docker currently has huge performance issues on macOS, and using Vagrant allows us to have an almost 
+Indeed, Docker currently has substantial performance issues on macOS, and using Vagrant allows us to have an almost 
 Linux-like experience regarding performances.
 
 #### Windows
@@ -50,7 +52,7 @@ If you're using Vagrant, check there is no application running on port 80 (like
 If OK, run `make vagrant`, then `vagrant up`, and finally `vagrant ssh` to connect to the virtual machine. 
 From here, you'll be able to run all the next commands like Linux users!
 
-> Update the variable `PROJECT_NAME` from the [Makefile](Makefile) with your project name.
+> Update the variable `VAGRANT_PROJECT_NAME` from the [Makefile](Makefile) with your project name.
 > Only use alphanumeric characters (no spaces, distinguish words with `_` or `-`).
 
 ### Starting the Docker Compose stack
@@ -161,20 +163,13 @@ Make sure you have read the following documentations:
 **Day-to-day guidelines**
 
 * [Web application guidelines](src/webapp/README.md)
-* [API guidelines](src/api/README.md)
+* [API guidelines](src/api/README.md)``
 
 **In-depth explanations**
 
-* [Configuration - development environment, API, web application](docs/configuration.md)
-* [Security](docs/security.md)
-* [Internationalization (i18n)](docs/i18n.md)
-* [Emails](docs/emails.md)
-* [Forms validation](docs/forms_validation.md)
-* [Lists](docs/lists.md)
-* [Resources - assets, temporary files, uploaded files](docs/resources.md)
-* [Housekeeping - or how to keep everything up-to-date](docs/housekeeping.md)
+* https://thecodingmachine.github.io/symfony-boilerplate/docs/VERSION
 
-> Don't hesitate to update these documentations but also add your documentations.
+> Update the previous link with the version of the boilerplate in use.
 
 ### How to stop the stack?
 

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/1_Get Started/1_1_Overview.md

@@ -0,0 +1,38 @@
+---
+title: Overview
+slug: /
+---
+
+The Symfony Boilerplate provides a dummy application with core concepts and functionalities to help you build 
+a modern web application.
+
+Many services compose this boilerplate.
+
+## Application layer
+
+This layer has two services:
+
+1. The GraphQL API, built with Symfony 5 and [GraphQLite](https://graphqlite.thecodingmachine.io/).
+2. The Web Application, built with Nuxt.js.
+
+## Data layer
+
+This layer has 3 services:
+
+1. MySQL for hosting session and business data.
+2. Redis for asynchronous tasks (e.g., emails).
+3. [MinIO](https://min.io/) for storing files (e.g., uploads).
+
+:::note
+
+In production, you may externalize them to the equivalent services from your provider.
+
+:::
+
+## Additional services
+
+These services are mostly useful in development:
+
+1. [Traefik](https://doc.traefik.io/traefik/), a reverse proxy.
+2. [MailHog](https://github.com/mailhog/MailHog), an email trapper with a web UI.
+3. phpMyAdmin, a web UI for displaying your database's data.

docs/docs/1_Get Started/1_2_Installation.md

@@ -0,0 +1,30 @@
+---
+title: Installation
+slug: /installation
+---
+
+Create your Git repository on the platform of your choice, then add a new remote to it:
+
+```bash title="console"
+git remote add boilerplate https://github.com/thecodingmachine/symfony-boilerplate.git
+```
+
+Finally, pull the source code from a [release](https://github.com/thecodingmachine/symfony-boilerplate/tags) to 
+your current branch:
+
+```bash script title="console"
+git pull boilerplate [TAG]
+```
+
+You may now follow the instructions of the *README*! 😋
+
+:::note
+
+There are comments on the *README* to help you customize its content.
+
+:::
+
+
+
+
+

docs/docs/2_Development Environment/2_1_Docker Compose.md

@@ -0,0 +1,148 @@
+---
+title: Docker Compose
+slug: /development-environment/docker-compose
+---
+
+[Docker](https://docs.docker.com) and [Docker Compose](https://docs.docker.com/compose/) are the core technologies that orchestrate the
+services of the boilerplate.
+
+They will help you set up a complete development environment close to your target production infrastructure.
+
+## Usage
+
+* 🚀 `make up`: starts the Docker Compose stack.
+* 💣 `make down`: stops the Docker Compose stack.
+* 📢 `docker-compose logs -f`: displays the logs of **all** your services.
+* 📢 `docker-compose logs -f [SERVICE_NAME]` displays the logs of one service.
+
+## Configuration
+
+Your development environment mostly consists of two files:
+
+* *docker-compose.yml*
+* *.env* file (and its template *.env.dist*)
+
+The *docker-compose.yml* file lists all the services of the boilerplate and their configuration.
+The services use mostly environment variables to configure themselves.
+Most of the time, you will set their values directly in the *docker-compose.yml* file.
+
+However, you don't want to commit your secrets to your Git repository. Also, you may want to reuse some values across
+different services.
+
+Docker Compose provides an easy way for such scenarios; it can read the values from the *.env* file.
+
+For instance:
+
+```.env title=".env"
+FOO=hello
+```
+
+```yaml title="docker-compose.yml"
+service_foo:
+    environment:
+      FOO: "$FOO"
+```
+
+Becomes at runtime (e.g., when running a Docker Compose command):
+
+```yaml
+service_foo:
+    environment:
+      FOO: "hello"
+```
+
+:::note
+
+When adding a new variable in the *.env* file, don't forget to update the template *.env.dist* with it.
+It will help other developers to notice this change and update their *.env* files accordingly.
+
+You should never commit the *.env* file as it may contain secrets; always use dummy values for your secrets 
+in the *.env.dist* template.
+
+:::
+
+## Add a new service
+
+The existing services might not be enough for your use cases.
+You may therefore add new services to your *docker-compose.yml* file.
+
+### Application layer
+
+```yaml title="docker-compose.yml"
+services:
+
+    your_service_name:
+        image: an_image:a_tag
+        labels:
+            - traefik.enable=true
+            - traefik.http.routers.your_service_name_router.rule=Host(`your_service_subdomain.$DOMAIN`)
+            - traefik.http.routers.your_service_name_router.service=your_service_name_service
+            # If your service runs on another port than 80.
+            # - traefik.http.services.your_service_name_service.loadbalancer.server.port=3000
+        environment:
+            FOO: "BAR"
+        volumes:
+            - src/your_service_source_code_folder:/path/in/the/docker/container    
+```
+
+:::note
+
+Always add a service code source in the *src* folder.
+
+:::
+
+### Data layer
+
+```yaml title="docker-compose.yml"
+services:
+
+    your_service_name:
+        image: an_image:a_tag
+        environment:
+            FOO: "BAR"
+        volumes:
+            - your_service_name_data:/path/in/the/docker/container
+
+volumes:
+
+      your_service_name_data:
+        driver: local
+```
+
+## Extend a Docker image
+
+You might need to extend a Docker image for installing one or more packages.
+
+For instance, let's say you want to install the `pdftk` package for the API:
+
+```dockerfile title="src/api/Dockerfile"
+FROM thecodingmachine/php:7.4-v3-apache AS extended
+
+# Always use the root user for installing packages.
+USER root
+
+# Install PDFtk.
+RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends pdftk &&\
+    # Print versions of PDFtk.
+    pdftk --version
+
+# Go back to the default Docker image user.
+USER docker
+
+FROM extended
+# Your production Docker image instructions.
+```
+
+```yaml title="docker-compose.yml"
+api:
+  #image: thecodingmachine/php:7.4-v3-apache
+  build:
+    context: "./src/api"
+    target: "extended"
+```
+
+```makefile title="Makefile"
+# Start the Docker Compose stack.
+up:
+    docker-compose up --build -d
+```

docs/docs/2_Development Environment/2_2_Vagrant.md

@@ -0,0 +1,38 @@
+---
+title: Vagrant
+slug: /development-environment/vagrant
+---
+
+On macOS and Windows, Docker currently has substantial performance issues.
+
+[Vagrant](https://www.vagrantup.com/) will help you to have an almost Linux-like experience regarding performances.
+
+## Usage
+
+* 📦 `make vagrant`: creates the *Vagrantfile*.
+* 🚀 `vagrant up`: installs and starts the virtual machine.
+* 🚇 `vagrant ssh`: connects to the virtual machine.
+* 🚦 `vagrant halt`: stops the virtual machine.
+* 💣 `vagrant destroy`: destroys the virtual machine.
+
+## Configuration
+
+Vagrant's configuration consists of three files:
+
+* *Makefile*
+* *scripts/create-vagrantfile-from-template.sh*
+* *Vagrantfile* (and its template *Vagrantfile.template*)
+
+The *Makefile* contains the variables `VAGRANT_BOX`, `VAGRANT_PROJECT_NAME`, `VAGRANT_MEMORY`, `VAGRANT_CPUS`, 
+and `VAGRANT_DOCKER_COMPOSE_VERSION`.
+
+The command `make vagrant` reads these variables and uses them as arguments 
+when calling the *create-vagrantfile-from-template.sh* script.
+
+The later replaces placeholders from the *Vagrantfile.template* by the variables' values and creates a new *Vagrantfile*.
+
+:::note
+
+You should never commit the *Vagrantfile*.
+
+:::