Docker & Nixpacks Deployments

Learn how to build and run containerized workloads using Nixpacks, custom Dockerfiles, or pre-built container registries.

1. Nixpacks Auto-Detection

If your repository doesn't include a Dockerfile, TurboV defaults to Nixpacks—an intelligent container compiler that automatically detects your language, framework, dependencies, and start commands:

Supported Runtimes Out-of-the-Box

Node.js: Next.js, Remix, Nuxt, Astro, SvelteKit, Express, Fastify, NestJS (detects package.json, pnpm-lock.yaml, yarn.lock, bun.lockb)
Python: Django, Flask, FastAPI, Celery (detects requirements.txt, Pipfile, pyproject.toml)
Go: Gin, Echo, Fiber, standard library (detects go.mod, go.sum)
Rust: Actix, Axum, Rocket (detects Cargo.toml, Cargo.lock)
Ruby: Ruby on Rails, Sinatra (detects Gemfile)
PHP: Laravel, Symfony (detects composer.json)

Nixpacks builds are reproducible, multi-layered, and automatically cached between deployments for rapid build times.

2. Custom Dockerfile Builds

For maximum control over your system dependencies, compile flags, or runtime binaries, include a standard Dockerfile in your repository:

Example Multi-Stage Dockerfile (Node.js)

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
 
# Stage 2: Builder
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN yarn build
 
# Stage 3: Production Runner
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
EXPOSE 3000
ENV PORT=3000
CMD ["node", "server.js"]

Dockerfile Settings

In Application Settings → Build Method:

Dockerfile Path: Set custom relative path (e.g. docker/production.Dockerfile).
Build Context: Specify the root directory for Docker build context.
Target Stage: Build only up to a specific stage in a multi-stage Dockerfile.

3. Deploying Pre-Built Docker Images

If your organization compiles container images in external CI/CD pipelines (such as GitHub Actions or GitLab CI), you can deploy pre-built images directly:

In the application creation screen, select Deploy Docker Image.
Specify the full image tag:
```
ghcr.io/my-org/api-service:v2.4.1
```
Set the exposed internal container port (e.g. 8080).

4. Private Container Registry Credentials

To pull images from private registries, configure credentials in Organization Settings → Registry Credentials:

Registry Type	Host URL	Username	Authentication Secret
Docker Hub	`https://index.docker.io/v1/`	Docker ID	Personal Access Token (PAT)
GitHub Packages (GHCR)	`ghcr.io`	GitHub Username	Personal Access Token with `read:packages`
AWS ECR	`<account_id>.dkr.ecr.<region>.amazonaws.com`	`AWS`	AWS Secret Access Key or IAM Token
Self-Hosted	`registry.yourdomain.com`	Custom	Registry Password or Token

The agent authenticates securely with the target registry before pulling images. Credentials are encrypted at rest with envelope encryption.

5. Container Resource Limits

Prevent noisy neighbors or runaway memory leaks by configuring container quotas in Application Settings → Resources:

Memory Limit: Maximum RAM the container can consume before being throttled or terminated (e.g. 512MB, 2GB).
Memory Reservation: Minimum guaranteed RAM allocated to the container.
CPU Quota: CPU execution quota (e.g. 0.5 cores, 2.0 cores).