TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

Adonis Sail

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


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

Available services

  • PostgreSQL
  • MySQL
  • Redis
  • MinIO
  • MailHog


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.


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 :


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


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 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 :


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 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


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

  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'),


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.

Package Sidebar


npm i adonis-sail

Weekly Downloads






Unpacked Size

27.1 kB

Total Files


Last publish


  • julien-r44