fix(cli): ensure network before stateful deploy, move convex to stateful compose, add convex to CI (#1526)

Author: larryro

.github/workflows/build.yml

@@ -65,6 +65,8 @@ jobs:
               - 'services/db/**'
             proxy:
               - 'services/proxy/**'
+            convex:
+              - 'services/convex/**'
             ci_tests:
               - 'tests/container-*'
               - 'compose.test.yml'
@@ -104,6 +106,8 @@ jobs:
             context: '.'
           - service: proxy
             context: '.'
+          - service: convex
+            context: '.'
 
     steps:
       - name: Checkout repository
@@ -243,6 +247,8 @@ jobs:
             context: '.'
           - service: proxy
             context: '.'
+          - service: convex
+            context: '.'
 
     steps:
       - name: Checkout repository

.github/workflows/release.yml

@@ -61,7 +61,7 @@ jobs:
         run: |
           VERSION="${{ needs.prepare.outputs.version_number }}"
           REGISTRY="${{ env.REGISTRY }}/${{ github.repository }}"
-          for svc in platform rag crawler db proxy; do
+          for svc in platform rag crawler db proxy convex; do
             IMAGE="${REGISTRY}/tale-${svc}:${VERSION}"
             echo "Verifying manifest: ${IMAGE}"
             docker manifest inspect "${IMAGE}" > /dev/null 2>&1 || {
@@ -103,6 +103,8 @@ jobs:
             context: '.'
           - name: proxy
             context: '.'
+          - name: convex
+            context: '.'
         arch:
           - name: amd64
             runner: ubuntu-latest
@@ -116,7 +118,7 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Free disk space
-        if: matrix.service.name == 'platform' || matrix.service.name == 'rag' || matrix.service.name == 'crawler'
+        if: matrix.service.name == 'platform' || matrix.service.name == 'rag' || matrix.service.name == 'crawler' || matrix.service.name == 'convex'
         run: |
           sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
           sudo docker image prune -af
@@ -188,7 +190,7 @@ jobs:
         run: |
           VERSION="${{ needs.prepare.outputs.version_number }}"
           ARCH="amd64"
-          for svc in platform rag crawler db proxy; do
+          for svc in platform rag crawler db proxy convex; do
             IMAGE="${{ env.REGISTRY }}/${{ github.repository }}/tale-${svc}:${VERSION}-${ARCH}"
             echo "Pulling ${IMAGE}..."
             docker pull "${IMAGE}"
@@ -226,7 +228,7 @@ jobs:
 
     strategy:
       matrix:
-        service: [platform, rag, crawler, db, proxy]
+        service: [platform, rag, crawler, db, proxy, convex]
 
     steps:
       - name: Log in to GHCR
@@ -288,7 +290,7 @@ jobs:
         run: |
           echo "## Release ${{ needs.prepare.outputs.version }} Complete" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          echo "All 5 service images have been built, tested, and pushed to GHCR (native amd64 + arm64)." >> $GITHUB_STEP_SUMMARY
+          echo "All 6 service images have been built, tested, and pushed to GHCR (native amd64 + arm64)." >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Images" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
@@ -299,6 +301,7 @@ jobs:
           echo "| Crawler | \`${{ env.REGISTRY }}/${{ github.repository }}/tale-crawler:${{ needs.prepare.outputs.version_number }}\` |" >> $GITHUB_STEP_SUMMARY
           echo "| DB | \`${{ env.REGISTRY }}/${{ github.repository }}/tale-db:${{ needs.prepare.outputs.version_number }}\` |" >> $GITHUB_STEP_SUMMARY
           echo "| Proxy | \`${{ env.REGISTRY }}/${{ github.repository }}/tale-proxy:${{ needs.prepare.outputs.version_number }}\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Convex | \`${{ env.REGISTRY }}/${{ github.repository }}/tale-convex:${{ needs.prepare.outputs.version_number }}\` |" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### CLI" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY

tests/container-image-test.sh

@@ -35,6 +35,7 @@ declare -A SIZE_BUDGETS=(
     [platform]=2900
     [db]=1200
     [proxy]=100
+    [convex]=2500
 )
 
 header() {
@@ -75,7 +76,7 @@ get_image() {
 cd "${PROJECT_ROOT}"
 header "Building all images locally"
 
-SERVICES=(crawler rag platform db proxy)
+SERVICES=(crawler rag platform db proxy convex)
 declare -A IMAGES
 
 echo -e "  ${YELLOW}Building images using compose...${NC}"
@@ -126,9 +127,9 @@ for svc in "${SERVICES[@]}"; do
             # Platform runs as root initially, then drops to 'app' user via gosu in entrypoint
             pass "${svc}: root (expected — gosu to app at runtime)"
             ;;
-        db)
-            # DB runs as root initially, then gosu to postgres — this is expected
-            pass "${svc}: root (expected — gosu to postgres at runtime)"
+        db|convex)
+            # DB/Convex run as root initially, then drop privileges via gosu in entrypoint
+            pass "${svc}: root (expected — gosu to app/postgres at runtime)"
             ;;
         proxy)
             # Caddy Alpine image — non-root not required

tools/cli/src/commands/deploy/index.ts

@@ -4,6 +4,7 @@ import { deploy } from '../../lib/actions/deploy';
 import {
   type ServiceName,
   ALL_SERVICES,
+  STATEFUL_SERVICES,
   isValidService,
 } from '../../lib/compose/types';
 import { ensureEnv } from '../../lib/config/ensure-env';
@@ -17,7 +18,11 @@ export function createDeployCommand(): Command {
   return new Command('deploy')
     .description('Deploy a version to the environment')
     .argument('[version]', 'Version to deploy (e.g., v1.0.0 or 1.0.0)')
-    .option('-a, --all', 'Also update infrastructure (db, proxy)', false)
+    .option(
+      '-a, --all',
+      `Also update infrastructure (${STATEFUL_SERVICES.join(', ')})`,
+      false,
+    )
     .option(
       '-s, --services <list>',
       `Specific services to update (comma-separated: ${ALL_SERVICES.join(',')})`,

tools/cli/src/commands/logs.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 
 import { logs } from '../lib/actions/logs';
+import { ALL_SERVICES } from '../lib/compose/types';
 import { requireProject } from '../lib/project/find-project';
 import { resolveProjectContext } from '../lib/project/project-context';
 import { loadEnv } from '../utils/load-env';
@@ -9,10 +10,7 @@ import * as logger from '../utils/logger';
 export function createLogsCommand(): Command {
   return new Command('logs')
     .description('View logs from a service')
-    .argument(
-      '<service>',
-      'Service name (platform, rag, crawler, search, db, proxy)',
-    )
+    .argument('<service>', `Service name (${ALL_SERVICES.join(', ')})`)
     .option('-c, --color <color>', 'Deployment color (blue or green)')
     .option('-f, --follow', 'Follow log output', false)
     .option('--since <duration>', 'Show logs since duration (e.g., 1h, 30m)')

tools/cli/src/commands/reset.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 
 import { reset } from '../lib/actions/reset';
+import { STATEFUL_SERVICES } from '../lib/compose/types';
 import { ensureEnv } from '../lib/config/ensure-env';
 import { requireProject } from '../lib/project/find-project';
 import { resolveProjectContext } from '../lib/project/project-context';
@@ -11,7 +12,11 @@ export function createResetCommand(): Command {
   return new Command('reset')
     .description('Remove ALL blue-green containers')
     .option('-f, --force', 'Skip confirmation prompt', false)
-    .option('-a, --all', 'Also remove infrastructure (db, proxy)', false)
+    .option(
+      '-a, --all',
+      `Also remove infrastructure (${STATEFUL_SERVICES.join(', ')})`,
+      false,
+    )
     .option('--dry-run', 'Preview reset without making changes', false)
     .action(async (options) => {
       try {

tools/cli/src/lib/actions/deploy.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 
 import { getProjectId, type DeploymentEnv } from '../../utils/load-env';
 import * as logger from '../../utils/logger';
+import { REQUIRED_VOLUMES } from '../compose/generators/constants';
 import { generateColorCompose } from '../compose/generators/generate-color-compose';
 import { generateStatefulCompose } from '../compose/generators/generate-stateful-compose';
 import {
@@ -32,17 +33,6 @@ import { withLock } from '../state/with-lock';
 import { MIGRATIONS } from '../upgrade/registry';
 import { runPendingMigrations } from '../upgrade/runner';
 
-const REQUIRED_VOLUMES = [
-  // platform-data is kept for upgrade scenarios where split-convex migrates
-  // its contents into convex-data; on fresh installs it is an unused empty
-  // volume. Removing it would break detect() for pre-0.3.0 deployments.
-  'platform-data',
-  'convex-data',
-  'caddy-data',
-  'rag-data',
-  'crawler-data',
-];
-
 async function ensureInfrastructure(
   prefix: string,
   dryRun: boolean,
@@ -56,7 +46,7 @@ async function ensureInfrastructure(
     return;
   }
 
-  const volumesCreated = await ensureVolumes(REQUIRED_VOLUMES);
+  const volumesCreated = await ensureVolumes([...REQUIRED_VOLUMES]);
   if (!volumesCreated) {
     throw new Error('Failed to create required volumes');
   }
@@ -273,12 +263,18 @@ export async function deploy(options: DeployOptions): Promise<void> {
         }
       }
 
+      // Must run AFTER migrations (which may `docker compose down`, removing
+      // networks) and BEFORE any `docker compose up` for stateful or rotatable
+      // services.
+      await ensureInfrastructure(prefix, dryRun);
+
       // Deploy stateful services if any
       if (statefulToUpdate.length > 0) {
         logger.step(`${prefix}Deploying stateful services...`);
         const statefulCompose = generateStatefulCompose(
           serviceConfig,
           hostAlias,
+          { fresh: options.fresh },
         );
 
         if (dryRun) {
@@ -341,16 +337,11 @@ export async function deploy(options: DeployOptions): Promise<void> {
             }
           }
 
-          await ensureInfrastructure(prefix, dryRun);
-
           // Update services in current color
           logger.step(`${prefix}Updating ${currentColor} services...`);
           const colorCompose = generateColorCompose(
             serviceConfig,
             currentColor,
-            {
-              fresh: options.fresh,
-            },
           );
 
           if (dryRun) {
@@ -420,13 +411,9 @@ export async function deploy(options: DeployOptions): Promise<void> {
             }
           }
 
-          await ensureInfrastructure(prefix, dryRun);
-
           // Deploy new color
           logger.step(`${prefix}Deploying ${nextColor} services...`);
-          const colorCompose = generateColorCompose(serviceConfig, nextColor, {
-            fresh: options.fresh,
-          });
+          const colorCompose = generateColorCompose(serviceConfig, nextColor);
 
           if (dryRun) {
             for (const service of rotatableToUpdate) {

tools/cli/src/lib/actions/reset.ts

@@ -23,7 +23,7 @@ export async function reset(options: ResetOptions): Promise<void> {
 
   logger.warn('This will remove ALL blue-green containers');
   if (includeStateful) {
-    logger.warn('Including stateful services: db, proxy');
+    logger.warn(`Including stateful services: ${STATEFUL_SERVICES.join(', ')}`);
   }
 
   if (!force) {
@@ -136,7 +136,9 @@ export async function reset(options: ResetOptions): Promise<void> {
       logger.success('Reset complete! All blue-green containers removed');
     }
     if (!includeStateful) {
-      logger.info('Stateful services (db, proxy) were preserved');
+      logger.info(
+        `Stateful services (${STATEFUL_SERVICES.join(', ')}) were preserved`,
+      );
       logger.info('Use --all to remove them as well');
     }
   });

tools/cli/src/lib/actions/rollback.ts

@@ -1,8 +1,11 @@
 import { getProjectId, type DeploymentEnv } from '../../utils/load-env';
 import * as logger from '../../utils/logger';
+import { REQUIRED_VOLUMES } from '../compose/generators/constants';
 import { generateColorCompose } from '../compose/generators/generate-color-compose';
 import { ROTATABLE_SERVICES } from '../compose/types';
 import { dockerCompose } from '../docker/docker-compose';
+import { ensureNetwork } from '../docker/ensure-network';
+import { ensureVolumes } from '../docker/ensure-volumes';
 import { getContainerVersion } from '../docker/get-container-version';
 import { pullImage } from '../docker/pull-image';
 import { removeContainer } from '../docker/remove-container';
@@ -87,6 +90,10 @@ export async function rollback(options: RollbackOptions): Promise<void> {
       await removeContainer(containerName);
     }
 
+    // Ensure infrastructure exists before compose up
+    await ensureVolumes([...REQUIRED_VOLUMES]);
+    await ensureNetwork('internal');
+
     // Deploy rollback color
     logger.step(
       `Deploying ${rollbackColor} services with version ${rollbackVersion}...`,

tools/cli/src/lib/compose/generators/constants.ts

@@ -14,6 +14,23 @@ export const DEV_VOLUME_NAMES = [
   'crawler-data',
 ] as const;
 
+// All volumes that must exist before any `docker compose up` in production.
+// Every volume declared as `external: true` in the stateful or color compose
+// must appear here so `ensureVolumes` pre-creates it.
+export const REQUIRED_VOLUMES = [
+  // platform-data is kept for upgrade scenarios where split-convex migrates
+  // its contents into convex-data; on fresh installs it is an unused empty
+  // volume. Removing it would break detect() for pre-0.3.0 deployments.
+  'platform-data',
+  'convex-data',
+  'caddy-data',
+  'caddy-config',
+  'db-data',
+  'db-backup',
+  'rag-data',
+  'crawler-data',
+] as const;
+
 // Enables containers to reach host services (e.g. Ollama on localhost:11434)
 // via `host.docker.internal`. `host-gateway` requires Docker 20.10+ (project
 // already requires 24.0+). Safe on Docker Desktop where host.docker.internal