Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/julien-r44/adonis-sail
⛵Generate a ready-to-use local docker environment for your Adonis application
https://github.com/julien-r44/adonis-sail
adonisjs docker docker-compose
Last synced: 13 days ago
JSON representation
⛵Generate a ready-to-use local docker environment for your Adonis application
- Host: GitHub
- URL: https://github.com/julien-r44/adonis-sail
- Owner: Julien-R44
- License: mit
- Created: 2021-12-29T19:15:59.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-17T19:25:46.000Z (10 months ago)
- Last Synced: 2024-10-05T06:48:40.171Z (about 1 month ago)
- Topics: adonisjs, docker, docker-compose
- Language: TypeScript
- Homepage:
- Size: 216 KB
- Stars: 99
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
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 `[email protected]`
```
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](https://docs.adonisjs.com/guides/drive#s3-driver) 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` :
```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](https://tableplus.com/).
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](https://docs.adonisjs.com/guides/mailer). 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.
```ts
...
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 :
```bash
npm install mysql2
```
And now configure Adonis to use it, in config/database.ts :
```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.