AdonisJS

What is AdonisJS?

AdonisJS is a TypeScript-first web framework for Node.js. It gives you everything you need to build production-grade applications with a focus on developer experience and type safety.

Key features:

• Full TypeScript Support: Write fully typed code from the start
• MVC Architecture: Clean separation between models, views, and controllers
• Lucid ORM: Elegant database abstraction layer
• Built-in Authentication: User authentication out of the box
• Validation: Robust request validation system

Galaxy handles the Node.js runtime for you. Just push your code, and Galaxy runs your AdonisJS app.

Prerequisites

Before deploying your AdonisJS app, ensure you have:

• An active Galaxy account (sign up here if needed)
• Your AdonisJS app in a GitHub repository
• Basic knowledge of AdonisJS and deployment concepts

Getting Started

Head over to the Web Apps Deployment Guide and follow the general deployment steps. Then come back here for AdonisJS-specific details about required files and configuration.

Required Files

Make sure your repository includes these essential files:

package.json

This is required. Galaxy reads your package.json to understand your dependencies and how to run your app.

{
  "name": "my-adonis-app",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=20.6.0"
  },
  "scripts": {
    "start": "node bin/server.js",
    "build": "node ace build",
    "dev": "node ace serve --hmr",
    "test": "node ace test"
  },
  "dependencies": {
    "@adonisjs/core": "^6.2.0",
    "@adonisjs/lucid": "^20.1.0",
    "@adonisjs/auth": "^9.1.0",
    "reflect-metadata": "^0.2.1"
  },
  "devDependencies": {
    "@adonisjs/assembler": "^7.1.0",
    "typescript": "^5.3.3"
  }
}

Key fields:

• scripts.start: Points to bin/server.js where Galaxy starts your app
• scripts.build: Compiles your TypeScript before deployment
• type: "module": AdonisJS 6.x uses ES modules
• dependencies: Include @adonisjs/core and other core packages

adonisrc.ts

Your AdonisJS configuration file at the root of your project:

import { defineConfig } from '@adonisjs/core/app'

export default defineConfig({
  typescript: {
    ignoreDiagnostics: false,
  },
  commands: [
    () => import('@adonisjs/core/commands'),
  ],
  providers: [
    () => import('@adonisjs/core/providers/app_provider'),
    () => import('@adonisjs/core/providers/hash_provider'),
  ],
})

tsconfig.json

Your TypeScript configuration:

{
  "extends": "@adonisjs/tsconfig/tsconfig.app.json",
  "compilerOptions": {
    "rootDir": "./",
    "outDir": "./build"
  }
}

.gitignore

Make sure your git repo excludes files that shouldn't be committed:

node_modules/
build/
.env
.env.local
.DS_Store
npm-debug.log*
yarn-debug.log*
dist/
.next/
out/

Important: Never commit .env files with secrets. Use environment variables in Galaxy instead.

Environment Variables Reference

These are the variables your AdonisJS app needs. Set them in the Galaxy deployment form.

Required Variables

Optional Variables

Database Variables

If you're using a database, add these variables:

DB_CONNECTION=pg
DB_HOST=your-postgres-host
DB_PORT=5432
DB_USER=your-username
DB_PASSWORD=your-password
DB_DATABASE=your-database

DB_CONNECTION=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USER=your-username
DB_PASSWORD=your-password
DB_DATABASE=your-database

DB_CONNECTION=sqlite
DB_DATABASE=./database/db.sqlite3

Advanced Configuration

Custom Build Commands

If you need additional build steps, override the defaults in your package.json:

{
  "scripts": {
    "build": "node ace build --production && node ace optimize",
    "start": "node bin/server.js"
  }
}

Then in Galaxy, set Build Command to npm run build.

Health Check Endpoint

Create a simple health check endpoint for Galaxy to monitor:

// start/routes.ts
import router from '@adonisjs/core/services/router'

router.get('/health', async ({ response }) => {
  return response.ok({
    status: 'healthy',
    timestamp: new Date().toISOString()
  })
})

In the Galaxy deployment form, set Health Check Path to /health. Galaxy checks this endpoint regularly. If it fails, Galaxy knows something's wrong.

Database Configuration

If using Galaxy's managed databases, update your database config:

// config/database.ts
import { defineConfig } from '@adonisjs/lucid'
import env from '#start/env'

const dbConfig = defineConfig({
  connection: env.get('DB_CONNECTION', 'pg'),
  connections: {
    pg: {
      client: 'pg',
      connection: {
        connectionString: env.get('DATABASE_URL'),
        ssl: {
          rejectUnauthorized: false
        }
      },
      pool: {
        min: 2,
        max: 10
      }
    }
  }
})

Running Migrations

Set up automatic database migrations on deployment:

{
  "scripts": {
    "build": "node ace build",
    "migrate": "node ace migration:run --force"
  }
}

Then configure in Galaxy:

1. Go to Settings then Deploy Hooks
2. Add Post-Build Command: npm run migrate

Troubleshooting

Build Failures

npm install
npm run build
npm start

Application Won't Start

# Generate a new key locally
node ace generate:key

# This outputs a 32-character key
# Copy it and paste into Galaxy environment variables

// bin/server.ts
await app.listen(process.env.PORT || 3333)

Database Connection Issues

Performance Issues

Slow response times?

1. Enable Production Mode: Verify NODE_ENV=production is set
2. Optimize Database Queries: Use eager loading to prevent N+1 queries

   const users = await User.query().preload('posts')

3. Add Caching: Use Redis or in-memory caching for frequently accessed data
4. Scale Your App: Increase container size or add more containers from the Galaxy dashboard

Resources

• AdonisJS Documentation
• AdonisJS GitHub
• Lucid ORM Documentation
• Galaxy Community Forum

Need Help?

Having trouble deploying your AdonisJS app?

• Community Forum
• Galaxy Support
• Knowledge Base