Setup Guide
Create a new project from SWAT, run it locally and prepare it for automated deployment.
PHP 8.2+
Required
Composer
Required
npm or yarn
Required
Symfony CLI
Optional but recommended
SWAT is designed to be used as a GitHub template repository.
Open the repository on GitHub, click Use this template, create your own repository,
then clone it locally and install the project dependencies.
# Clone your new repository created from the SWAT template
git clone https://github.com/your-username/your-project.git
# Enter the project directory
cd your-project
# Install PHP dependencies
composer install
# Install frontend dependencies
npm install
# Build frontend assets for development
npm run dev
# With Symfony CLI (recommended)
symfony serve
# Without Symfony CLI
php -S localhost:8000 -t public
Open your application at http://localhost:8000 to confirm that Symfony, Twig, TypeScript and SCSS are running correctly.
Open local SWAT home page
This step is optional, but recommended if you want to start from a clean base.
SWAT includes example pages, assets and tests used to demonstrate the structure
and verify that the stack works correctly.
Once your environment is confirmed to work, you can remove this example content
and keep only the base project structure.
# These commands remove the example pages, assets and tests from the project
# Review them first and adjust them if needed before running
# On Windows
.\scripts\cleanup\clean-example-files.ps1
# On Linux or macOS
./scripts/cleanup/clean-example-files.sh
Once your local environment is ready, review the provided CI/CD workflows and adapt them to your own hosting strategy.
The ci.yml workflow validates the project on pull requests.
It is designed to work out of the box for most projects and also checks the Doctrine setup by running test migrations,
validating the schema and ensuring that no migration diff is pending.
The deploy-preprod.yml and deploy-production.yml workflows should be adapted to your server setup and deployment process.
As a rule of thumb, deploy-preprod.yml is a good starting point for Docker or reverse-proxy-based environments,
while deploy-production.yml is a good starting point for a more traditional hosting setup or a VPS with SSH access.
SWAT also includes automatic Doctrine migration execution during deployment.
In both preproduction and production, the workflow can create the database if needed and run migrations to keep the schema in sync with the application code.
SWAT includes GitHub Actions workflows for preproduction and production deployment. To use them, add the required SSH and server secrets in your repository settings.
| Variable name | Description |
|---|---|
| PREPROD_HOST / PROD_HOST | The hostname or IP address of the preproduction or production server. |
| PREPROD_PORT / PROD_PORT | The SSH port used to connect to the preproduction or production server. |
| PREPROD_USER / PROD_USER | The SSH user used for the preproduction or production deployment. |
| PREPROD_PATH / PROD_PATH | The deployment path on the preproduction or production server. |
| PREPROD_SSH_KEY / PROD_SSH_KEY | The private SSH key used by GitHub Actions to connect to the target server. |
| PREPROD_KNOWN_HOSTS / PROD_KNOWN_HOSTS | The known hosts value used to verify the identity of the target server during SSH connection. |
To keep your deployment workflow safe and consistent, configure branch protection rules on both
dev and master.
Go to your repository settings and create a branch protection rule for each branch.
| Recommended rules | Description |
|---|---|
| Require a pull request before merging | Ensures that all changes go through a pull request before they are merged. |
| Require status checks to pass before merging | Ensures that the CI checks pass before allowing a merge. |
| Require branches to be up to date before merging | Ensures that the branch is synchronized with the base branch before merging. |
| Require conversation resolution before merging | Ensures that pull request discussions are resolved before allowing a merge. |
The provided GitHub Actions workflows include validation checks for build and tests. To make your branch protection rules effective, add these checks as required status checks in your branch configuration.
SWAT uses environment variables to configure Symfony in production.
Make sure to set the correct values on each server for a smooth deployment experience.
Each server must contain a .env.local file adapted to its environment.
This file contains the real environment-specific values used by Symfony in production.
An example .env file is included in the project as a generic base configuration.
# Example .env.local configuration
APP_ENV=prod
APP_DEBUG=0
APP_SECRET=<random secret>
DATABASE_URL=<database url>
DEFAULT_URI=<default uri>
# TRUSTED_PROXIES is only required if your application runs behind a reverse proxy
TRUSTED_PROXIES=127.0.0.1,REMOTE_ADDR
Your project is now ready to use, and your deployment pipeline is configured.
On your next pull request, the validation workflow will run and check the project.
Once you merge into dev, the preproduction deployment workflow will deploy the application to your staging environment.
When you are ready for production, merge into master and create a new version tag to trigger the production deployment workflow.
You now have a working project base, a validation pipeline and a deployment workflow ready to evolve with your application.