Questions from first AdonisJS deploy with Catapult

[filipebraida]

Hi! First time using Catapult on an AdonisJS 7 + pnpm monorepo project. The tool worked great, got us from zero to a running deploy in a few iterations. Wanted to ask a few questions and share observations that might help other newcomers (or might just be my misunderstandings).

1. Stale lock after interrupted deploy

If the local cata deploy is interrupted (Ctrl+C, network drop) between deploy:lock and deploy:unlock, the lock file remains on the host and the next cata deploy won't proceed.

I had to SSH in and remove the lock file manually.

2. AdonisJS .env in production server vs in build/

The adonisjs recipe sets shared_files: ['.env'] and the deploy:shared task creates a symlink at release_path/<adonisjs_path>/.env.

That works for node ace migration:run (uses source ace.js which reads .env from apps//).

But the production HTTP server runs from build/bin/server.js. The compiled build/start/env.js calls:

Env.create(new URL('../', import.meta.url), {...})

From build/start/env.js, '../' resolves to build/. So AdonisJS reads .env from build/.env, which the recipe doesn't create.

Workaround I added in deploy.ts:

task('adonisjs:link-env', () => {
  run('ln -sfn ../.env {{release_path}}/{{adonisjs_path}}/build/.env')
})
after('adonisjs:build', 'adonisjs:link-env')

Question: am I missing a recipe option? If not, would it make sense to bake this into the adonisjs recipe?

Thanks for the great tool!

[batosai]

Hello, thank you for this feedback.

You should know that the package is in alpha and in constant evolution/refacto.

Be careful to check the pipeline after each update.

I am aware of these problems. For the lock, I haven’t started working on it yet. It is possible to manually launch the task unlock `npx cata task deploy:unlockˋ
For adonisjs, I’m on the refacto of the recipe.

Which version do you use? Do you use rsync or git?

Here is the sharing I can do on what is happening:

There will be 2 modes to meet everyone’s needs:

• Local (will be the default): build in local and transfer by scp(default) or rsync.

• Remote: build on the server in a directory.catapultJS/builder

But the monorepo are very special, I think about it but I don’t see how to anticipate them all. I also have in prod a monorepo pnpm adonisjs + directus + nuxt with the same problem.

[batosai]

I would provide in the next version complete examples for adonisjs and show the configuration for each mode (strategy). I would be delighted to have your return at that time.

[filipebraida]

Hi! Thanks for the response.

I was actually looking for a way to simplify deployments, and your package came at a perfect time. I don’t have experience with deployment tools from ecosystems like Ruby or PHP, so this was something new for me. I’m more used to configuring everything manually.

In my current setup, I cannot connect to the server via SSH directly and have to rely on a web-based system (Teleport) to perform configuration. Because of that, the “remote” mode you mentioned would be really helpful, especially if it allows running the deploy from within the machine itself.

I also ran into a few issues with PM2. I had to remove it to get the refresh working properly, as it seemed to get stuck pointing to an old symlink.

Regarding the monorepo, my case is quite simple for now. I only have a single application, so it behaves basically like a standard AdonisJS build, just located in a different directory.

What I tested was a project that I deployed mainly to showcase a new proposal to people at my university. It actually made things easier, especially because it already leaves the project well structured.

If I need to set up a new server, I basically just need to install the database and Node, which is great.

I’d be happy to help by providing feedback. I’d really like to contribute in some way, as I think this project can make deployments much easier.

[batosai]

I’m glad to see your interest in the project.

Regarding PM2, this also came up during my testing. The solution is to use absolute paths so that PM2 correctly resolves current instead of the release. I will provide a complete example soon.

I’m not familiar with “Teleport” systems, and I’m not sure I explained the remote mode clearly.
Both local and remote modes use SSH. The main difference lies in the build step (local vs. on the server).

What would be the ideal scenario for your hosting setup? I’d be curious to know whether a custom recipe, overriding some tasks, could address your needs.

[filipebraida]

Great! I can test this on my side. I can also share the examples I’ve already built if that helps.

Regarding Teleport, it’s not really about the tool itself. What I meant is a scenario where the deploy happens on the same machine (self-deploy). I wouldn’t be able to run a remote deploy from my local environment, but your tool could still be very useful if it supports running everything from within the server itself.

In that setup, I could also imagine extending it in the future to handle things like database backups and other operational tasks through the same interface.

These are basically my current use cases. What you’re planning would already help a lot, and in the future I would probably use both approaches depending on the scenario.

deploy.ts

import { after, defineConfig, run, set, task } from '@catapultjs/deploy'
import { Verbose } from '@catapultjs/deploy/enums'
import '@catapultjs/deploy/recipes/adonisjs'
import '@catapultjs/deploy/recipes/git'
import '@catapultjs/deploy/recipes/pm2'

set('adonisjs_path', '/apps/web')
set('shared_files', ['apps/web/.env'])
set('shared_dirs', ['apps/web/storage', 'apps/web/logs'])
set('writable_dirs', ['apps/web/storage', 'apps/web/logs', 'apps/web/tmp'])

task('adonisjs:link-env', () => {
  run('ln -sfn ../.env {{release_path}}/apps/web/build/.env')
})
after('adonisjs:build', 'adonisjs:link-env')

export default defineConfig({
  keepReleases: 5,

  repository: 'git@github.com:filipebraida/projectx.git',

  hosts: [
    {
      name: 'production',
      ssh: 'deploy@projectx.university.com.br',
      deployPath: '/home/deploy/projectx',
      branch: 'main',
      healthcheck: {
        url: 'http://localhost:3333/health/live',
        retries: 10,
        delayMs: 3000,
      },
    },
  ],

  verbose: Verbose.NORMAL, // SILENT | NORMAL | TRACE | DEBUG
})

ecosystem.config.cjs

const commonEnv = {
  LANG: 'pt_BR.UTF-8',
  LC_ALL: 'pt_BR.UTF-8',
  LC_PAPER: 'pt_BR.UTF-8',
}

const CWD_PREFIX = process.env.CWD_PREFIX || ''

module.exports = {
  apps: [
    {
      name: 'web',
      cwd: `./${CWD_PREFIX}apps/web/build`,
      script: 'bin/server.js',
      instances: 1,
      exec_mode: 'fork',
      autorestart: true,
      watch: false,
      max_memory_restart: '512M',
      env: {
        NODE_ENV: 'production',
        ...commonEnv,
      },
    },
  ],
}

[batosai]

Hello @filipebraida,

I’ve released the new version 0.6.0.

This version should fix both of your issues, with one small nuance:

In a monorepo setup, combining multiple recipes will inevitably require some manual task overrides, because recipes can replace standard tasks (such as deploy:build, for example).

The monorepo setup is quite specific and remains largely the developer’s responsibility.

In your case — a simple monorepo with a single recipe — there should be no issue. You should be able to write:

import { after, defineConfig, run, set, task } from '@catapultjs/deploy'
import { Verbose } from '@catapultjs/deploy/enums'
import '@catapultjs/deploy/recipes/adonisjs'
import '@catapultjs/deploy/recipes/git'
import '@catapultjs/deploy/recipes/pm2'

set('adonisjs_path', '/apps/web')
set('shared_files', ['apps/web/.env'])
set('shared_dirs', ['apps/web/storage', 'apps/web/logs'])
set('writable_dirs', ['apps/web/storage', 'apps/web/logs', 'apps/web/tmp'])

export default defineConfig({
  hosts: [
    {
      name: 'production',
      ssh: 'deploy@projectx.university.com.br',
      deployPath: '/home/deploy/projectx',
      branch: 'main',
      healthcheck: {
        url: 'http://localhost:3333/health/live',
        retries: 10,
        delayMs: 3000,
      },
    },
  ],

  verbose: Verbose.NORMAL, // SILENT | NORMAL | TRACE | DEBUG
})