Laravel
Wondering how to configure Tugboat for a Laravel project? One of the claims of Laravel is “One Framework, Many Flavors”, so every Laravel project tends to have different requirements. You may need to do some customizing, but this should get you started.
The following documentation assumes you are using Composer to manage your Laravel project, and that you are using Blade templates styled with Tailwind CSS; as frontend tooling, your choice is Vite.
If you are using Livewire or Inertia, or any other option, it should be pretty similar.
Configuring Laravel
A common practice for managing Laravel settings is to leave sensitive information, such as database credentials, in
environment variables. For development, you might have a an .env.dev or .env.example file on git.
This pattern works very well with Tugboat. It lets you keep a Tugboat-specific set of configurations in your repository, where you can copy it into place with a configuration file command.
So let’s create a .tugboat/.env.tugboat with your variables, and customize it for tugboat. You might want to base it
on your production values, or, less common, your dev environment values as a basis. The choice is yours. But for sure
you want to configure these values:
APP_URL=${TUGBOAT_DEFAULT_SERVICE_URL_HOST}
LOG_CHANNEL=stderr
DB_CONNECTION="mysql"
DB_HOST=database
DB_PORT=3306
DB_DATABASE=tugboat
DB_USERNAME=tugboat
DB_PASSWORD=tugboat
MAIL_MAILER=smtp
MAIL_HOST=${TUGBOAT_SMTP}
MAIL_PORT=25
FILESYSTEM_DISK=local
QUEUE_CONNECTION=database
CACHE_STORE=database
CACHE_PREFIX=- The
APP_URLwill use an environment variable for setting the url host. - The
LOG_CHANNELwill be the standard output, as this way we will see it more easily on the Tugboat UI or via the Tugboat CLI without needing to open a shell on it. - The
DB_*variables will depend on the database engine you pick on yourconfig.yml, this assumes mysql. - The
MAIL_*variables will point to tugboat SMTP server, so the mails are never delivered but instead captured and visible on your preview dashboard. - For files and queue system, you will use the local filesystem and database respectively, but more complex options are also supported.
- You could also set your
APP_KEYhere with${TUGBOAT_REPO_ID}.
See Enviroment variables for more options on environment variables available.
Configure Tugboat
The Tugboat configuration is managed by a YAML file at
.tugboat/config.yml in the git repository. Here’s a basic configuration you can use as a starting point, with comments
to explain what’s going on:
1# Default Laravel 11 Tugboat starter config.
2# https://docs.tugboatqa.com/starter-configs/tutorials/laravel/
3services:
4 # What to call the service hosting the site.
5 webserver:
6 # This uses PHP 8.3.x with Apache: update to match your version of PHP.
7 image: tugboatqa/php:8.3-apache
8
9 # Set this as the default service. This does a few things
10 # 1. Clones the git repository into the service container
11 # 2. Exposes port 80 to the Tugboat HTTP proxy
12 # 3. Routes requests to the preview URL to this service
13 default: true
14 # Wait until the mysql service is done building.
15 depends: database
16
17 # A set of commands to run while building this service
18 commands:
19 # Commands that set up the basic preview infrastructure
20 init:
21 # Install opcache and mod-rewrite.
22 - docker-php-ext-install opcache
23 - a2enmod headers rewrite
24 # Install node
25 - apt-get update
26 - apt-get install -yq ca-certificates curl gnupg
27 - mkdir -p /etc/apt/keyrings
28 - curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o
29 /etc/apt/keyrings/nodesource.gpg
30 - echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_18.x nodistro main" |
31 tee /etc/apt/sources.list.d/nodesource.list
32 - apt-get update
33 - apt-get install -yq nodejs
34 # Copy the tugboat .env we created before
35 - cp "${TUGBOAT_ROOT}/.tugboat/.env.tugboat" "${TUGBOAT_ROOT}/.env"
36 # Link the document root to the expected path. This example links
37 # /public to the docroot
38 - ln -snf "${TUGBOAT_ROOT}/public" "${DOCROOT}"
39 # Ensure storage permissions
40 - chgrp -R www-data "${TUGBOAT_ROOT}/storage"
41 - find "${TUGBOAT_ROOT}/storage" -type d -exec chmod 2775 {} \;
42 - find "${TUGBOAT_ROOT}/storage" -type f -exec chmod 0664 {} \;
43 # Composer install
44 - composer install --optimize-autoloader
45 # Generate the random key if you didn't set APP_KEY before.
46 - php artisan key:generate
47 # Install the workers
48 - mkdir -p /etc/service/webserver
49 - cp .tugboat/etc/service/webserver/run /etc/service/webserver/run
50 - chmod +x /etc/service/webserver/run
51 update:
52 # Clear caches.
53 - php artisan config:cache
54 # Generate the db structure with some data. Here you have several choices:
55 # 1. If you have seeders on your project, you might just run migrate with --seed.
56 # - php artisan migrate --seed
57 # 2. You might want just the structure without any test data.
58 # - php artisan migrate
59 # 3. Or you might load a database dump from somewhere else. That's up to you.
60 # If that's your case you might want to do that in the database update step though.
61 - php artisan migrate --seed
62 # Compile vite templates
63 - npm install
64 - npm run build
65 build:
66 - composer install --optimize-autoloader
67 # Clear caches.
68 - php artisan config:cache
69 # Run any pending migrations. This will ensure your data has the last
70 # migrations applied.
71 - php artisan migrate --force
72 # Compile vite templates
73 - npm install
74 - npm run build
75
76 database:
77 # Use the latest available version of MariaDB by not specifying a
78 # version
79 image: tugboatqa/mariadb:10.5Configuring queue runners
At the end of the init step, you can see that we are copying a .tugboat/etc/service/webserver/run file and marking
it as executable. This is a quick way of having a background process.
In this .tugboat/etc/service/webserver/run we are going to run the default worker of your Laravel application:
1#!/bin/sh
2su -s /bin/bash -c 'cd ${TUGBOAT_ROOT} && php artisan queue:work' www-dataIf you want to customize your queue runners, have separate runners per queue, or any other customization, read Running a Background Process for more information.
Want to know more about something mentioned in the comments of this config file? Check out these topics:
- Name your Service
- Specify a Service image
- Leverage Service commands
- Define a default Service
- Set the document root path
- Set up remote SSH access
- Preview build process phases (
init,update,build) - How Base Previews work
- Running a Background Process
Start Building Previews!
Once the Tugboat configuration file is committed to your git repository, you can start building previews!