NEXUS CLI Full App Deployments, Workers, and Scaling

By NEXUS AI Team · Contact: nexusai.run/contact

This guide explains how to deploy a full application from Git with the NEXUS CLI, attach database/cache services, add a background worker process, and scale.

Prerequisites

• NEXUS CLI installed and authenticated.
• A project/repository with a Dockerfile or framework files NEXUS can build.
• Local Docker provider when using attached services such as PostgreSQL and Redis. Cloud providers do not currently support Compose-managed attached services.

Check the CLI:

nexus --version
nexus auth status

Deploy A Full App From Git

Use nexus deploy source for full application deployments from a repository.

nexus deploy source \
  --repo https://github.com/acme/postsfinders.git \
  --name postsfinders \
  --provider docker \
  --framework python \
  --branch main \
  --wait

Useful options:

--name <name>                 Deployment name
--branch <branch>             Git branch
--provider docker             Use local Docker deployment
--framework <framework>       Framework hint, for example python, node, fastapi
--build-command <cmd>         Custom build command
--start-command <cmd>         Custom web process command
--install-command <cmd>       Custom install command
--env KEY=VALUE               Runtime environment variable
--env-file .env.production    Load env vars from a file
--wait                        Wait until deployment is RUNNING or FAILED

Example with env vars:

nexus deploy source \
  --repo https://github.com/acme/postsfinders.git \
  --name postsfinders \
  --provider docker \
  --framework python \
  --env FLASK_ENV=production \
  --env QUEUE=default \
  --wait

Attach Database And Cache Services

Attach services with --services. These services are created in the same Docker Compose deployment as the app.

nexus deploy source \
  --repo https://github.com/acme/postsfinders.git \
  --name postsfinders \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --wait

The app receives service environment variables such as:

POSTGRES_HOST=postgresql
POSTGRES_PORT=5432
POSTGRES_DB=appdb
POSTGRES_USER=appuser
POSTGRES_PASSWORD=<generated>
DATABASE_URL=postgresql://appuser:<generated>@postgresql:5432/appdb
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URL=redis://redis:6379/0

Inside the Compose network, use service hostnames:

postgresql:5432
redis:6379

Do not use localhost for database/cache connections from the app or worker container.

Add A Worker Service

Use --worker-command to run a background worker alongside the web app. The worker uses the same built app image and attaches to the same service network as the app, PostgreSQL, Redis, and any other attached resources.

RQ example:

nexus deploy source \
  --repo https://github.com/acme/postsfinders.git \
  --name postsfinders \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --worker-command "rq worker default" \
  --worker-name worker \
  --wait

Celery example:

nexus deploy source \
  --repo https://github.com/acme/postsfinders.git \
  --name postsfinders \
  --provider docker \
  --framework python \
  --services postgresql,redis \
  --worker-command "celery -A app.celery worker --loglevel=info" \
  --worker-name celery-worker \
  --wait

Node worker example:

nexus deploy source \
  --repo https://github.com/acme/jobs-api.git \
  --name jobs-api \
  --provider docker \
  --framework node \
  --services postgresql,redis \
  --worker-command "node worker.js" \
  --worker-name jobs-worker \
  --wait

Worker behavior:

• Runs from the same app image as the web service.
• Gets the same app environment variables.
• Can resolve postgresql, redis, and other attached service hostnames.
• Is not exposed publicly.
• Is not attached to Traefik.
• Does not allocate a host port.
• Does not create its own database/cache volume.

Scale The App Up

Scale app replicas with:

nexus deploy scale postsfinders 2

Scale higher:

nexus deploy scale postsfinders 3

Replica rules:

• Replica count must be between 1 and 10.
• App replicas are attached to the existing deployment service network.
• App replicas can resolve postgresql, redis, and other attached services.
• Attached database/cache services are not duplicated during app scaling.
• Worker sidecars are separate services and are not scaled by nexus deploy scale unless worker scaling is implemented separately.

Scale The App Down

Scale back down to one app replica:

nexus deploy scale postsfinders 1

View Logs

Use the CLI:

nexus deploy logs postsfinders --follow

Stop, Start, And Delete

Stop a deployment:

nexus deploy stop postsfinders

Start it again:

nexus deploy start postsfinders

Delete it:

nexus deploy delete postsfinders

Troubleshooting

Worker Cannot Resolve Redis Or PostgreSQL

Symptom:

Error -2 connecting to redis:6379. Name or service not known
failed to resolve host 'postgresql'

Fix:

• Ensure the worker was created with --worker-command.
• Ensure attached services were requested with --services postgresql,redis.
• Redeploy with the updated backend and CLI.

NEXUS removes app replicas by these labels when scaling down.

Compose Directory Missing

Older deployments may have lost the original temporary Compose directory. In that case, NEXUS falls back to app-only replica scaling on the existing service network and does not recreate database/cache services.

This protects existing database contents.

Start for free · Read the documentation · About NEXUS AI · Contact