novaserve-provider-docker
v2.2.4
Published
NovaServe Docker Provider — Containerize and deploy via Docker
Maintainers
Readme
NovaServe Docker Provider
The novaserve-provider-docker package provides production-ready deployment of NovaServe applications to Docker environments. It generates multi-stage Dockerfiles and Docker Compose orchestrations from your Nova IR configuration.
This provider transforms your serverless configuration into a robust, secure, and production-ready containerized application suitable for local hosting, VPS deployments, private clouds, or on-premise infrastructure.
Features
- Multi-stage Dockerfiles: Optimized builds utilizing
node:*-alpineor custom base images. - Production Compose Orchestration: Maps Nova resources (API, functions, workers, cron, databases, caches) to Docker Compose services.
- Security Hardened: Non-root users (
uid 1001), read-only root filesystems, dropped capabilities (cap_drop: ALL), andno-new-privilegesby default. - Health Checks: Wait-for-health deployment lifecycle using HTTP or command-based health checks.
- Dependency Bundling: Automatically bundle and orchestrate managed databases (PostgreSQL, MySQL, MongoDB, Redis) and S3-compatible object storage (MinIO) for fully self-hosted deployments.
- Graceful Shutdown: Sends
SIGTERMand handles configurable stop grace periods to prevent dropped connections. - Resource Limits: Apply CPU and memory limits (
deploy.resources) to individual containers or globally. - Secret Management: Safely isolates config from secrets using
.env.exampleplaceholder generation, avoiding committed secrets.
Installation
The Docker provider is included natively in the NovaServe CLI.
npm install novaserve-provider-dockerConfiguration
Configure the Docker provider in your nova.config.ts:
import { defineApp, api, database } from "novaserve";
export default defineApp({
name: "my-app",
provider: "docker", // Set default provider
docker: {
// Docker-specific settings
bundleDependencies: true, // Run local Postgres/Redis via Compose
restartPolicy: "unless-stopped",
stopGracePeriod: 30, // seconds
// Global resource limits
resources: {
limits: { cpus: "2", memory: "1G" },
reservations: { cpus: "0.5", memory: "256M" }
},
// Security options
security: {
nonRoot: true, // Run as 'novaserve' user
readOnlyRootFilesystem: true,
tmpfsMounts: ["/tmp"]
},
// Deployment health checks
healthCheck: {
type: "http",
endpoint: "/health",
interval: 15, // seconds
timeout: 5,
retries: 3
}
},
resources: {
api: api.create({ routes: { "GET /": "src/index.handler" } }),
db: database.postgres()
},
});Deployment Lifecycle
Deploy your application using the NovaServe CLI:
nova deploy --provider dockerThe Docker provider executes a robust deployment lifecycle:
- Artifact Generation: Generates
Dockerfile,compose.yaml,.dockerignore, and.envtemplates in.nova/docker/. - Build: Executes a BuildKit-optimized build of your application image.
- Deploy: Starts the infrastructure using
docker compose up -d. - Health Verification: Polls container health and HTTP health endpoints, ensuring the deployment is successful before marking it as ready.
- Registry Push (Optional): If configured, tags and pushes the image to your container registry.
Container Registry Integration
You can configure the provider to automatically push to a registry (Docker Hub, GHCR, ECR, etc.):
docker: {
registry: {
url: "ghcr.io",
repository: "my-org/my-app",
tagStrategy: "git-commit", // Uses current git commit hash
push: true
}
}Make sure you are authenticated with the registry (docker login ghcr.io) before deploying.
Secrets & Environment Variables
NovaServe strictly separates configuration from secrets. When deploying with Docker:
- The provider generates a
.env.examplecontaining all required environment variables with<CHANGE_ME>placeholders. - A
.envtemplate is also generated (if it does not exist) that automatically wires internal services together (e.g., automatically generatingDATABASE_URLlinking your API container to your Postgres container). - Secrets (defined via
secret()in NovaServe) are left blank in the.envtemplate. You must provide them at deployment time.
Warning: Never commit
.envfiles to version control. The provider automatically adds them to.dockerignoreand.gitignore.
Service Discovery (Dependency Bundling)
By default (bundleDependencies: false), the Docker provider assumes your databases and caches are hosted externally (e.g., RDS, ElastiCache) and expects you to provide connection strings via environment variables.
For fully self-hosted deployments, set docker.bundleDependencies = true. The provider will automatically inject containers for Postgres, MySQL, MongoDB, Redis, and MinIO into your Compose orchestration, create isolated internal networks, and wire the connection strings securely between containers.
Cleanup
To tear down the deployment:
nova destroy --provider dockerBy default, data volumes are retained to prevent accidental data loss. To remove volumes, run docker compose down --volumes manually in the .nova/docker/ directory.
