Catalyst App Deployment

Use this flow to deploy a Catalyst web app consisting of the SSR server and the emitted static assets.

Production Flow

  1. Build the production bundle with catalyst build or npm run build.
  2. Start the production server with catalyst serve, npm run serve, or a process manager entrypoint.
  3. Route logs to stdout and stderr so the app behaves well in containers and managed infrastructure.

Build Output

Catalyst 0.3.x produces:

  • client assets under build/client/
  • the server renderer under build/server/
  • Vite client and SSR manifests under build/.vite/
  • catalyst-offline-manifest.json and catalyst-sw.js at the build root

The Vite manifests and Catalyst asset metadata resolve route chunks and CSS during SSR.

Legacy Catalyst 0.2.x applications retain their webpack output layout, including build/public/ and loadable metadata. Do not change deployment paths until the application is upgraded to 0.3.x.

Required Configuration

Set production values in config/config.json before building:

  • NODE_SERVER_HOSTNAME
  • NODE_SERVER_PORT
  • PUBLIC_STATIC_ASSET_URL
  • PUBLIC_STATIC_ASSET_PATH
  • BUILD_OUTPUT_PATH

Use a production-ready PUBLIC_STATIC_ASSET_URL, especially when assets are served from a CDN or a dedicated static host.

Process Management

Catalyst apps are commonly run behind PM2 or inside a container. A typical PM2 runtime entrypoint looks like:

NODE_ENV=production BUILD_ENV=production pm2-runtime ./ecosystem.config.js --wait-ready --listen-timeout 15000

ecosystem.config.js usually controls:

  • process name
  • restart policy
  • memory limits
  • timeouts

Pre-Deploy Checklist

  • confirm production config values
  • verify the public asset URL matches the deployed asset host
  • validate SSR routes and metadata in the built app
  • confirm logs and monitoring are wired for the server process
  • smoke-test the built app with catalyst serve before shipping

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3005
CMD ["npm", "run", "serve"]