sample.nextdeploy.yml

# ==============================
# NEXTDEPLOY CONFIGURATION FILE
# ==============================
# This YAML defines everything needed to build, deploy, monitor, and scale your app on a VPS/SERVERlESS using NextDeploy.
# Think of it as your infrastructure-as-code for end-to-end delivery.

# NOTE: DO NOT ADD YOUR SECRETS AS OF NOW WE WORKING ON SECRET MANAGMENT THIS IS HOW WE INTENT TO USE
version: "1.0" # Config file versioning for forward compatibility with future NextDeploy updates

# -----
# TARGET TYPE — choose between "vps" (traditional server) or "serverless" (AWS Lambda + S3 + CloudFront)
# -----
target_type: vps  # "vps" | "serverless"

# -----
# APP METADATA
# -----
app:
  name: example-app # Unique app name used for container naming and logging
  environment: production # Can be: development | staging | production. Affects env variables & caching.
  domain: app.example.com # Public domain where your app will be accessible
  port: 3000 # Internal app port (e.g., what your Node/Go server listens on)

# -----
# DEPLOYMENT TARGET
# -----
deployment:
  server:
    host: 192.0.2.123 # IP of the VPS where your app will be deployed
    user: deploy # Linux user that NextDeploy connects as (ensure permissions are correct)
    ssh_key: ~/.ssh/nextdeploy_rsa # Private key used for SSH access to the server
    use_sudo: false # Set true if deployment user needs sudo for Docker/system commands

  container:
    name: example-app # Docker container name (must be unique per server)
    restart: always # Automatically restart container on failure or reboot
    env_file: .env # Relative path to your app's environment variables file
    volumes:
      - ./data:/app/data # Mount local folder (`./data`) into container at `/app/data`
    ports:
      - "80:3000" # Map public port 80 to container's port 3000 (so it's accessible on your domain)
    healthcheck:
      path: /api/health # API endpoint that returns 200 OK if the app is healthy
      interval: 30s # Check every 30 seconds
      timeout: 5s # Fail check if response isn't received within 5s
      retries: 3 # After 3 failed checks, container will be restarted

# -----
# DATABASE CONFIG
# -----
database:
  type: postgres # Supported: postgres | mysql
  host: 192.0.2.124 # IP of your database server (managed or self-hosted)
  port: 5432
  username: dbuser
  password: secret
  name: exampledb
  migrate_on_deploy: true # Run database migrations automatically after deployment

# Example:
#   - Use Amazon RDS or DigitalOcean Managed PostgreSQL as the database host.
#   - Schema is updated with migration tools like Goose, Flyway, or Prisma.

# -----
# LOGGING CONFIGURATION
# -----
logging:
  enabled: true # Enable logging system
  provider: nextdeploy # Use NextDeploy's internal logging daemon (alternatively: syslog, logtail, etc.)
  stream_logs: true # Send live container logs to dashboard (tail -f equivalent)
  log_path: /var/log/containers/example-app.log # Path on server where logs are persisted

# -----
# MONITORING & ALERTING
# -----
monitoring:
  enabled: true # Enables resource monitoring for CPU, memory, disk
  cpu_threshold: 80 # Alert if CPU usage goes over 80%
  memory_threshold: 75 # Alert if memory usage exceeds 75%
  disk_threshold: 90 # Alert if disk usage crosses 90%
  alert:
    email: ops@example.com # Email to send alerts to
    slack_webhook: https://hooks.slack.com/services/... # Slack channel webhook for real-time alerting
    notify_on:
      - crash # App/container crash
      - healthcheck_failed # Failed /api/health checks
      - high_cpu
      - high_memory

# Example:
#   - If your Go server crashes due to panic, or memory spikes over 75%, you get a Slack alert.
#   - Alerts also help you pre-emptively scale or investigate.

# -----
# BACKUP STRATEGY
# -----
backup:
  enabled: true # Enable automatic backups
  frequency: daily # Options: hourly | daily | weekly
  retention_days: 7 # Keep backups for 7 days
  storage:
    provider: s3 # Use S3-compatible storage (AWS S3, MinIO, Wasabi, etc.)
    bucket: nextdeploy-backups # S3 bucket name
    region: us-east-1 # AWS region
    access_key: YOUR_ACCESS_KEY
    secret_key: YOUR_SECRET_KEY

# Example:
#   - Database and volume data backed up to S3 every day.
#   - Automatically deleted after 7 days unless extended.

# -----
# SSL CONFIGURATION
# -----
ssl:
  enabled: true # Enable HTTPS
  provider: letsencrypt # Automatically issue and renew free SSL certs
  email: admin@example.com # For receiving expiry/renewal notices
  auto_renew: true # Automatically renew certificates every 60–90 days

# Example:
#   - NextDeploy auto-configures HTTPS for app.example.com using Let's Encrypt.
#   - No manual cert renewal needed.

# -----
# WEBHOOKS AFTER DEPLOYMENT
# -----
webhook:
  on_success:
    - curl -X POST https://your-api.com/deploy/success # Notify external system (e.g., Slack, Discord, CI dashboard)
  on_failure:
    - curl -X POST https://your-api.com/deploy/failure # Used for alerting, logging, or rollback triggers

# Example:
#   - You can hook this into Notion, Linear, Jira, Slack, or even a custom dashboard.
#   - Also useful for CI/CD chaining (e.g., notify QA team that staging is ready).

## CLOUD PROVIDER instructions

CloudProvider:
  name: aws # Supported: aws | gcp | azure | digitalocean
  region: us-north-1 # AWS region (e.g., us-east-1, eu-west-1)
  access_key: YOUR_AWS_ACCESS_KEY # IAM user access key
  secret_key: YOUR_AWS_SECRET_KEY # IAM user secret key
  vpc_id: vpc-12345678 # VPC ID for networking (if applicable)
  subnet_id: subnet-12345678 # Subnet ID for deploying resources

# -----
# SERVERLESS DEPLOYMENT (set target_type: serverless above to enable)
# -----
#
# ┌─────────────────────────────────────────────────────────────────────┐
# │ EXAMPLE A — AWS (Lambda + S3 + CloudFront)                          │
# │ Requires AWS credentials in env or ~/.aws/credentials               │
# └─────────────────────────────────────────────────────────────────────┘
# serverless:
#   provider: aws              # one of: aws | cloudflare
#   region: us-east-1          # AWS region for all resources
#   isrRevalidation: true      # Enable ISR cache listener Lambda via SQS
#   imageOptimization: true    # Enable on-the-fly Image Resization Lambda via CloudFront
#   warmer: true               # Keep the Lambda warm
#   s3_bucket: my-app-assets   # S3 bucket where public/ and _next/static/ are uploaded
#   cloudfront_id: EXXXXX      # CloudFront distribution ID — triggers cache invalidation after deploy
#   lambda_function_name: my-app-handler  # Lambda function name (defaults to app name if omitted)
#
# How it works (AWS):
#   1. `nextdeploy build` packages .next/standalone + public/ into .nextdeploy/app.tar.gz
#   2. `nextdeploy ship`:
#      a. Loads local secrets via SecretManager and pushes them to AWS Secrets Manager
#      b. Uploads public/ and _next/static/ to S3 with correct Content-Type and Cache-Control
#      c. Zips .next/standalone/ and deploys it to Lambda via UpdateFunctionCode
#      d. Injects ND_SECRETS_ARN into Lambda env vars so your app can fetch secrets at runtime
#      e. Creates a CloudFront invalidation (/*) to clear stale cached assets
#
# ┌─────────────────────────────────────────────────────────────────────┐
# │ EXAMPLE B — Cloudflare (Workers + R2)                               │
# │ Requires only CLOUDFLARE_API_TOKEN.  Account ID auto-discovers.     │
# │ R2 keys are optional — left unset, the deploy uses the API token.   │
# └─────────────────────────────────────────────────────────────────────┘
# serverless:
#   provider: cloudflare
#   cloudflare:
#     compatibility_date: "2025-04-01"
#     compatibility_flags: [nodejs_compat_v2]
#
#     # Custom domains attached to the Worker. The zone must already exist
#     # on your Cloudflare account (zone auto-creation is a roadmap item).
#     custom_domains:
#       - hostname: app.example.com
#       # - hostname: api.example.com
#
#     # Worker route patterns (alternative to custom_domains, e.g. for
#     # path-based routing onto a shared zone).
#     # routes:
#     #   - { zone: example.com, pattern: "example.com/*" }
#
#     # Cron triggers. NOTE: declared schedules are uploaded, but the
#     # bundled shim must export a scheduled() handler — see CLOUDFLARE_PARITY.md A1.
#     # triggers:
#     #   crons: ["0 */6 * * *"]
#
#     # Bindings the Worker sees as `env.<name>` at runtime.
#     bindings:
#       # R2 binding — auto-injected if you omit this block.
#       r2:
#         - { name: ASSETS, bucket: my-app-assets-prod }
#
#       # Hyperdrive (pooled SQL). Either reference a resource declared
#       # below by name, or paste an existing config id.
#       # hyperdrive:
#       #   - { name: DB, ref: primary }
#       #   - { name: REPLICA, id: 00000000-0000-0000-0000-000000000000 }
#
#       # Queues. Producers go on this worker; consumers attach this
#       # worker to a queue created elsewhere (or in resources below).
#       # queues:
#       #   producers:
#       #     - { name: JOBS, queue: jobs-prod }
#       #   consumers:
#       #     - { queue: jobs-prod, max_batch_size: 10, max_retries: 3 }
#
#       # Vectorize, AI Gateway, KV, Durable Objects, plain env vars.
#       # vectorize:    [{ name: VEC, index: prod-embeddings }]
#       # ai:           [{ name: AI,  gateway: { id: my-gateway } }]
#       # kv:           [{ name: KV,  namespace_id: <id> }]
#       # durable_objects:
#       #   - { name: COUNTER, class: Counter }
#       # plain_text:   [{ name: APP_VERSION, value: "1.2.3" }]
#
#     # Standalone resources to provision/converge before the Worker upload.
#     # Each block is idempotent: created on first run, updated on drift.
#     resources:
#       # hyperdrive:
#       #   - name: primary
#       #     origin_env: DATABASE_URL   # connection string read from secret
#       #     # origin: postgres://user:pass@host:5432/db
#       # queues:
#       #   - name: jobs-prod
#       # vectorize:
#       #   - { name: prod-embeddings, dimensions: 1536, metric: cosine }
#       # ai_gateway:
#       #   - { slug: my-gateway }
#
#       # DNS records on a CF-managed zone. Useful for pointing apex /
#       # www at the Worker, MX/TXT for email, etc.
#       dns:
#         - { zone: example.com, name: "@",  type: A,     content: 192.0.2.1, proxied: true }
#         - { zone: example.com, name: www,  type: CNAME, content: example.com, proxied: true }
#       # zone_settings:
#       #   - { zone: example.com, min_ttl: 60 }
#
# How it works (Cloudflare):
#   1. `nextdeploy build` produces .next/standalone (vanilla `next build` output).
#   2. `nextdeploy ship`:
#      a. Verifies CLOUDFLARE_API_TOKEN, auto-discovers account ID if unset.
#      b. Provisions standalone resources (Hyperdrive / Queues / Vectorize / DNS).
#      c. Uploads public/ and .next/static/ to an R2 bucket with correct Cache-Control.
#      d. Adapts .next/standalone into a single ESM Worker bundle via nextcompile +
#         esbuild (--conditions=workerd,worker,node), then uploads to Workers.
#      e. Wires custom domains, routes, cron triggers, queue consumers.
#      f. Pushes secrets to the Worker.
#      g. Purges the zone cache.
#
# Credentials (Cloudflare):
#   • CLOUDFLARE_API_TOKEN     — required. Covers everything except R2
#                                 object PUTs (which need S3-protocol auth).
#   • CLOUDFLARE_ACCOUNT_ID    — optional; auto-discovered if the token
#                                 sees exactly one account.
#
# R2 object credentials — pick ONE of:
#   (a) R2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY  (long-lived, S3-compat).
#   (b) R2_PARENT_ACCESS_KEY_ID  (just the access key id of a parent key —
#       nextdeploy will mint scoped 1-hour child creds via the API token at
#       deploy time. The parent's *secret* never leaves the dashboard).
# Both can also live in the encrypted credstore at ~/.nextdeploy/credstore
# (run `nextdeploy creds set --provider cloudflare`).
#
# Required token scopes — see `nextdeploy ship` error output, or:
#   Account: Workers Scripts:Edit, Workers Routes:Edit, Workers R2 Storage:Edit,
#            Account Settings:Read, plus per-resource scopes (Hyperdrive, D1,
#            Vectorize, AI Gateway) only if you use them.
#   Zone:    Zone:Read, DNS:Edit, Cache Purge:Purge (per zone you deploy to).

# -----
# SECRETS — Doppler workflow
# -----
#
# The recommended pattern is `doppler run -- nextdeploy ship`. Doppler
# injects every secret in your project/config as a process environment
# variable; nextdeploy auto-detects it (via DOPPLER_PROJECT in env),
# harvests SCREAMING_SNAKE_CASE keys (excluding tooling/credential
# prefixes like CLOUDFLARE_, AWS_, DOPPLER_, etc.), and pushes them as
# Worker secrets / Lambda secrets-manager entries.
#
# No nextdeploy.yml change is required for `doppler run -- ...`. Block
# below is only needed when you populate env from a non-`doppler run`
# source (CI step that wrote to $GITHUB_ENV, manual export, etc.) and
# want nextdeploy to still harvest it.
#
# secrets:
#   files:
#     - { path: .env.production }   # extra dotenv files to merge
#   doppler:
#     project: my-app               # informational; doppler run sets these in env
#     config:  prd
#     inject_env: true              # force env harvesting even outside `doppler run`
#
# Precedence (lowest → highest), values from later sources override earlier:
#   1. .env at project root
#   2. files declared in secrets.files[]
#   3. Doppler-injected process env (auto when DOPPLER_PROJECT is set)
#   4. .nextdeploy/.env  (managed store; written by `nextdeploy secrets set`)