Adonis Sail

⛵Generate a ready-to-use local docker environment for your Adonis application

Installation

Note

Looking for version for AdonisJS 5 ? Make sure to install adonis-sail@0.0.7

pnpm i --save-dev adonis-sail
node ace configure adonis-sail
node ace sail:install

Available services

• PostgreSQL
• MySQL
• Redis
• MinIO
• MailHog

Usage

Make sure to install needed Adonis Package, and follow instructions before running Sail's commands. @adonisjs/redis, @adonisjs/lucid, @adonisjs/drive-*, @adonisjs/mail.

Now you can set your environment variables. Many of these will also be used in the generated docker-compose (look inside once created to know which ones). Especially the *_PORT or *_PASSWORD.

Once this is done you can run the command node ace sail:install and select the services you want. A compose.yml file will be created at the root of your project, you now just have to launch it by doing docker compose up -d.

You can launch again the node ace sail:install command at any time to add new services.

MinIO

If you plan to use Amazon S3 to store files while running your application in its production environment, you may wish to install the MinIO service when installing Sail. MinIO provides an S3 compatible API that you may use to develop locally using Adonis's s3 storage driver without creating "test" storage buckets in your production S3 environment. If you choose to install MinIO while installing Sail, a MinIO configuration section will be added to your application's compose.yml file.

You will need to install the official Adonis drive-s3 package to use MinIO locally. So install the package by following the documentation correctly, then in your .env file, use these variables :

S3_KEY=sail
S3_SECRET=password
S3_BUCKET=local
S3_REGION=us-east-1
S3_ENDPOINT=http://localhost:9000

And add this to config/drive.ts :

...
  s3: {
      forcePathStyle: true, // 👈 Don't forget this !
      key: Env.get('S3_KEY'),
      secret: Env.get('S3_SECRET'),
      region: Env.get('S3_REGION'),
      bucket: Env.get('S3_BUCKET'),
      endpoint: Env.get('S3_ENDPOINT'),
  }
...

You can now use the @adonisjs/drive-s3 package to store and fetch files like you would do normally on a real AWS bucket. You can also access MinIO dashboard at : http://localhost:8900/dashboard

Databases

To connect to your application's databases from your local machine, you may use a graphical database management application such as TablePlus. By default, exposed ports are :

• MySQL: 3306
• PostgreSQL: 5432
• Redis: 6379

MailHog

MailHog intercepts emails sent by your application during local development and provides a convenient web interface so that you can preview your email messages in your browser. To use MailHog install install the official Adonis Mailer package. Follow the installation instructions, and select SMTP when prompted. You have to set theses variables in your .env file :

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USERNAME=
SMTP_PASSWORD=

In config/mail.ts, remove the auth part in the smtp configuration object.

...
  smtp: {
    driver: 'smtp',
    host: Env.get('SMTP_HOST'),
    port: Env.get('SMTP_PORT'),
  },
...

You can now access the MailHog dashboard at http://localhost:8025/ to preview emails.

Mailpit

Mailpit is an alternative to MailHog. It's a service that allows you to preview emails sent by your application during local development.

You can follow the same steps as for MailHog, and also access the Mailpit dashboard at http://localhost:8025/

Known issues

MySQL 8

If you are using MySQL 8 (the default image), and you encounter the following error:

ER_NOT_SUPPORTED_AUTH_MODE: 
  Client does not support authentication protocol requested by server; consider upgrading MySQL client 

You need to install mysql2 :

npm install mysql2

And now configure Adonis to use it, in config/database.ts :

...
mysql: {
  client: 'mysql2' // 👈 Set this to 'mysql2'
  connection: {
    user: Env.get('MYSQL_USER'),
    password: Env.get('MYSQL_PASSWORD'),
    database: Env.get('MYSQL_DB_NAME'),
  },
...

Details

Currently, the Adonis application is not dockerised. I rarely encountered problems on my applications depending on the version of Node.JS I use (it happens, but with a tool like nvm it's usually fixed pretty quickly). And it's obviously easier to handle your Adonis application when it's running outside a docker container. That's why I decided not to dockerise the Adonis app.