To use this template, you must have Spin installed.

spin new laravel my-laravel-app

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:

• https://serversideup.net/ca/

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: "[email protected]"

Change [email protected] 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:

1. You deployed a server and have SSH access
2. Set variables in .spin.yml
3. Added your server in .spin-inventory.yml
4. 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.