Documentation

This is a template of a README. Adapt it according to the comments and your needs.

Replace this title and the following description with your project name and description.

A web application built with Nuxt.js 2, Symfony 5.4 (LTS), and GraphQL 5.

Install the latest version of Docker and Docker Compose.

Consider installing Vagrant and VirtualBox.

Indeed, Docker currently has substantial performance issues on macOS, and using Vagrant allows us to have an almost Linux-like experience regarding performances.

Consider using a Linux-like terminal to run the Makefile commands. Vagrant might also be a solution regarding performances.

If not possible, you may also directly run the commands specified in the Makefile. For instance, instead of running make up, run docker-compose up -d.

Update your hosts file with the following entries:

127.0.0.1   traefik.symfony-boilerplate.localhost
127.0.0.1   symfony-boilerplate.localhost
127.0.0.1   api.symfony-boilerplate.localhost
127.0.0.1   phpmyadmin.symfony-boilerplate.localhost
127.0.0.1   minio.symfony-boilerplate.localhost
127.0.0.1   mailhog.symfony-boilerplate.localhost

Update the domain with the one used in your project.

On Linux and macOS, run sudo nano /etc/hosts to edit it.

On Windows, edit the file C:\Windows\System32\drivers\etc\hosts with administrative privileges.

Copy the file .env.dist to a file named .env. For instance:

cp .env.dist .env

Edit the .env.dist by updating the default values of DOMAIN, MYSQL_DATABASE and APP_SECRET environment variables.

"Comment" the STARTUP_COMMAND_3 and STARTUP_COMMAND_4 environment variables from the api service in the docker-compose.yml file.

Next, run:

docker-compose up webapp api

📣  This command start the webapp and api service. While booting, these services install the JavaScript and PHP dependencies. We cannot do that directly in the Vagrant VM as yarn and composer install fail miserably the first time.

Once the services have installed the dependencies, you may stop them with:

CTRL+C
docker-compose down

Don't forget to uncomment the previous environments variables from the api service in the docker-compose.yml file.

Next, check there is no application running on port 80 (like Apache or another virtual machine).

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 VAGRANT_PROJECT_NAME from the .env and .env.dist files with your project name. Only use alphanumeric characters (no spaces, distinguish words with _ or -).

Next, make sure there is no application running on port 80 (Vagrant users can skip this check).

Good? You may now start all the Docker containers with the following commands:

make up

It may take some time as each container will also set up itself, such as installing dependencies (PHP, JavaScript, etc.), compiling sources (JavaScript), or running migrations to set up the database structure.

📣  In some cases, the api service will try to run the migrations before the mysql service is ready. If so, restart the api service with docker-compose up -d api.

The containers will be ready faster next time you run this command as the first run is doing most of the setup.

Once everything is ready, the following endpoints should be available:

• http://traefik.symfony-boilerplate.localhost (Reverse proxy, the entry point of all the HTTP requests)
• http://symfony-boilerplate.localhost (Web application)
• http://api.symfony-boilerplate.localhost (API)
• http://phpmyadmin.symfony-boilerplate.localhost (phpMyAdmin, a web interface for your MySQL database)
• http://minio.symfony-boilerplate.localhost (S3 compatible storage)
• http://mailhog.symfony-boilerplate.localhost (Emails catcher)

Update the domain with the one used in your project.

You may now enter the api service and load the development data:

make api
php bin/console app:fixtures:dev
exit

Last but not least, start the message consumer with:

make consume

We have added cypress for front-end testing, for now it is in webapp directory. It is recommended to remove it went deploy in production for security reasons:

In the main directory

cd src/webapp
./node_modules/.bin/cypress open

Git should ignore globally some folders like those generated by your IDE and Vagrant.

If not already done, you should tell Git where to find your global .gitignore file.

For instance, on Linux/macOS/Windows git bash:

git config --global core.excludesfile '~/.gitignore'

Windows cmd:

git config --global core.excludesfile "%USERPROFILE%\.gitignore"

Windows PowerShell:

git config --global core.excludesfile "$Env:USERPROFILE\.gitignore"

Then create the global .gitignore file according to the location specified previously.

You may now edit it, according to your environment, with:

# IDE
.idea
.vscode
# MacOS
.DS_Store
# Vagrant
.vagrant

Make sure you have read the following documentations:

Day-to-day guidelines

• Web application guidelines
• API guidelines

In-depth explanations

• See docs folder.

As simple as the make up command, run make down to stop the entire Docker Compose stack.

If you're a Vagrant user, you may also stop the virtual machine with vagrant halt.

If you're not going to work on the project for a while, you may also destroy the virtual machine using vagrant destroy.

All aggregated logs:

docker-compose logs -f

Logs of one service:

docker-compose logs -f SERVICE_NAME

For instance, if you want the logs of the api service:

docker-compose logs -f api