Codeware Playground

A playground for multi stack and architecture powered by Codeware Sthlm.

Contents

• Packages
  • Nx Plugins
  • GitHub Actions
  • Node Libraries
  • Utilities
• Startup Payload multi-tenant in dev mode
  • Terminal 1: Start Postgres and admin UI
  • Terminal 2: Start web client
  • Terminal 3: Start reverse proxy to simulate multi-tenancy
• Development Tools & Services
  • Infisical Secrets Management
  • Fly.io Deployment
  • Release Management
• Deployment

Packages

Nx Plugins

nx-payload

Add support for Payload in your existing Nx workspace.

npx add @cdwr/nx-payload

create-nx-payload

Quickly create a new Nx workspace with a Payload application, using the plugin as a preset.

npx create-nx-payload

GitHub Actions

deploy-env-action

GitHub action that analyzes the environment to deploy to based on the event details.

nx-fly-deployment-action

GitHub action that brings automatic Fly.io deployments to your Nx workspace.

nx-migrate-action

GitHub action that brings automatic Nx migrations to your workspace.

nx-pre-deploy-action

GitHub action that brings pre-deployment analysis of environment, multi-tenancy and secrets to your workspace.

Node Libraries

fly-node

Fly CLI node wrapper for programmatic deployments to Fly.io.

Utilities

core

A set of core utilities for the Codeware ecosystem.

Startup Payload multi-tenant in dev mode

The Payload suite consists of

• Payload Admin UI (cms)
• Web Client (web)
• Docker Postgres Database
• Nginx Reverse Proxy to simulate multi-tenancy

Important

For a better DX you should not connect to Infisical in dev mode, since the development seed has much more data.

Make sure the credentials in the .env.local file are not set.

Terminal 1: Start Postgres and admin UI

Start Postgres in Docker

nx dx:postgres cms

Serve admin UI

nx serve cms

Note

Database is auto-seeded with static data when the admin UI is started.

Optional

Clear database and run migrations

nx payload cms migrate:fresh

Generate seed data

Seed data is stored in environment-specific TypeScript files in

• libs/shared/util/seed/src/lib/static-data.

You can remove the existing seed data and keep just an empty object to force the generation of new seed data.

nx seed cms

Terminal 2: Start web client

Note

Live-reload is not fully operational.

nx start web

Terminal 3: Start reverse proxy to simulate multi-tenancy

nx payload-proxy:up

Note

You can now access the different web sites as different tenants:

🌐 cms.localhost

🙎 system@local.dev @ dev

Optional

Stop the proxy

nx payload-proxy:down

Communicate with the proxy

nx payload-proxy [docker compose options]

Development Tools & Services

Infisical Secrets Management

The Infisical secret management tool is used to manage secrets for the Codeware ecosystem.

[!NOTE] Deployment and multi-tenant configuration See: DEPLOYMENT.md and the multi-tenant setup guide

1. Install Infisical CLI

2. Login to access the secrets

   infisical login

3. List the development secrets

   # all secrets
   infisical secrets --recursive
   
   # cms application (all secrets and some by tag)
   infisical secrets --recursive --path /cms
   infisical secrets --tag cms
   
   # web application (all secrets and some by tag)
   infisical secrets --recursive --path /web
   infisical secrets --tag web
   
   # 'demo' tenant using web application
   infisical secrets --path /web/tenants/demo

Using the secrets

Add Infisical creadentials to you local environment.

apps/cms/.env.local

# Alt 1: Client credentials
INFISICAL_CLIENT_ID=
INFISICAL_CLIENT_SECRET=

# Alt 2: Service token
INFISICAL_SERVICE_TOKEN=

Note

Secrets can also be injected into process.env for any command, but this is not how we normally do it.

infisical run --path [path] -- [command]

Fly.io Deployment

The Fly.io platform is used to host the deployed applications and the required services.

[!NOTE] Configuration, multi-tenant setup, and workflow details See: DEPLOYMENT.md

Deployments are automatic on push events, detected by the nx-fly-deployment-action.

For local development and troubleshooting, install the Fly CLI:

1. Install Fly CLI

2. Login to your Fly account

   fly auth login

3. List the applications (for example)

   fly apps list

Database setup for preview deployments

Applications affected by a pull request are deployed to a temporary preview environment. A Fly Postgres cluster pg-preview is used to store the temporary databases, with automatic attachment/detachment managed by the deployment workflow.

[!NOTE] How to configure Postgres attachment in github.json See: DEPLOYMENT.md

Advanced: Postgres cluster commands

# Create a Postgres cluster (use only one node to prevent HA issues for unmananged cluser)
fly pg create --name pg-preview --org codeware --region arn --vm-size shared-cpu-2x --volume-size 1 --initial-cluster-size 1

# Detach application from the Postgres cluster
fly pg detach pg-preview -a cdwr-cms-pr-{pr-number}

# Delete application
fly apps destroy cdwr-cms-pr-{pr-number}

# List all Postgres databases
fly pg db list -a pg-preview

Database Maintenance & Troubleshooting

Cleanup dangling database (after PR is closed):

sh scripts/cleanup-db.sh {pr-number} {cluster-password}

Drop database (to start fresh):

sh scripts/drop-db.sh {pr-number} {cluster-password}
fly machine stop {machine-id}
fly machine restart {machine-id}

Connect to preview database locally:

# Forward port (5433 to avoid conflicts with local Docker Postgres)
fly proxy 5433:5432 -a pg-preview

# Connection string
postgres://postgres:<password>@localhost:5433

Release Management

The release process is semi-automatic which means:

• Releases are generated from a local machine by a developer
• GitHub action trigger on the tags and publish to NPM

Simply run the following command to start the release process:

nx release-cli

Deployment

This workspace uses automated GitHub Actions to deploy applications to Fly.io with support for both single-tenant and multi-tenant architectures. The deployment system:

• Automatically detects affected applications using Nx
• Fetches tenant configuration from Infisical
• Deploys to the appropriate environment (preview/production)
• Supports per-app tenant lists for flexible multi-tenancy

For comprehensive deployment documentation, including configuration, multi-tenant setup, and troubleshooting, see DEPLOYMENT.md.