Warning
This repo is experimental and currently under construction. Check back for more details later 👷♂️🚧🏗️
To use this template, you must have Spin installed.
spin new laravel my-laravel-app
Caution
There are settings to change before you can use this template.
We have the development URL set up to work under the *.dev.test
domain. This also includes wildcard certificates that will trust connections on this domain as well.
To get your machine to recognize these domains, add the following to your /etc/hosts
file:
127.0.0.1 laravel.dev.test
127.0.0.1 mailpit.dev.test
Change laravel
to your app name or whatever you would like to use. For the best experience, just make sure it ends in .dev.test
.
This file is used for development. You'll need to make the following changes:
If you want HTTPS to work, you need to let Let's Encrypt know what domain you are using. You can do this by changing the docker-compose.prod.yml
file.
labels:
- "traefik.enable=true"
- "traefik.http.routers.laravel.rule=Host(`laravel.dev.test`)"
This file is used for production deployments. You'll need to make the following changes:
If you're using CI/CD, you'll likely want to change the image name in the docker-compose.prod.yml
file.
php:
image: ${SPIN_IMAGE_NAME} # 👈 Change this if you're not using `spin deploy`
Set this value to the published image with your repository.
If you want HTTPS to work, you need to let Let's Encrypt know what domain you are using. You can do this by changing the docker-compose.prod.yml
file.
labels:
- "traefik.enable=true"
- "traefik.http.routers.my-php-app.rule=Host(`myapp.example.com`)"
Change myapp.example.com
to your domain name.
If you run spin deploy
, we include a variable called SPIN_TRAEFIK_CONFIG_MD5_HASH
that ensures the Swarm Configuration is always up to date.
If you're not using spin deploy
, you may need to change this value:
configs:
traefik:
name: "traefik-${SPIN_TRAEFIK_CONFIG_MD5_HASH}.yml"
file: ./.infrastructure/conf/traefik/prod/traefik.yml
We provide certificates by default. If you'd like to trust these certificates, you need to install the CA on your machine.
Download the CA Certificate:
You can change these files out if you'd like to use your own certificates.
If you'd like Let's Encrypt to work, you need to change the email address in the traefik/prod/traefik.yml
file.
certificatesResolvers:
letsencryptresolver:
acme:
email: "changeme@example.com"
Change changeme@example.com
to a valid email address.
By default, this template is configured to work with spin deploy
out of the box. If you prefer to use CI/CD to deploy your files (which isn't a bad idea), you will need to make your own changes to these files. These files should still give you a good head start.
Before running spin deploy
, ensure you configured:
- You deployed a server and have SSH access
- Set variables in
.spin.yml
- Added your server in
.spin-inventory.yml
- You successfully completed
spin provision
Once the steps above are complete, you can run spin deploy
to deploy your application:
spin deploy <environment-name>
If you're using an existing project with SQLite, you will need to move your database to a volume, especially if you're deploying to production with these templates.
Laravel comes with the default path of database/database.sqlite
. This path is not ideal for Docker deployments, because the parent directory of this file contains other database files used by Laravel.
For Docker Swarm (what is used in production), we need to place the SQLite in a dedicated folder so we can mount a Docker Volume to ensure the data persists.
To prepare the project, we automatically set the DB_DATABASE
environment variable.
# Set absolute path to SQLite database from the container's perspective
DB_DATABASE=/var/www/html/.infrastructure/volume_data/database.sqlite
NOTE: Notice how this is the ABSOLUTE path to the database file. The reason why we use /var/www/html
is because that is the absolute path to the file in the eyes of the CONTAINER (not the host machine).
Your project folder is mounted as /var/www/html
inside the container. You simply need to ensure the .infrastructure/volume_data/database.sqlite
file exists in your project folder on your host. Move your existing database file to this location if you want to migrate your data.
We automatically create a database_sqlite
volume in production. This volume is mounted to /var/www/html/.infrastructure/volume_data/sqlite/
to the php
service.