Blueprint Spec Reference

Complete reference for the railpush.yaml file format.

Root Fields

Field	Type	Description
services	Array	Web services, workers, cron jobs, static sites
databases	Array	PostgreSQL database instances
keyValues	Array	Redis key-value stores
envVarGroups	Array	Shared environment variable groups

Service Fields

Field	Type	Required	Description
name	String	Yes	Unique service name within the blueprint
type	String	No	web (default), pserv, worker, cron, static
runtime	String	Yes*	node, python, go, ruby, rust, docker, elixir, static, image
repo	String	No	Repository URL (defaults to blueprint repo)
branch	String	No	Git branch (defaults to blueprint branch)
buildCommand	String	No	Build command
startCommand	String	No	Start command (ignored for static sites)
dockerCommand	String	No	Docker CMD override
dockerfilePath	String	No	Custom Dockerfile path
dockerContext	String	No	Build context directory (alias: buildContext)
buildContext	String	No	Alias for dockerContext (preferred for non-Docker builds)
rootDir	String	No	Root directory for monorepos
port	Int	No	HTTP port (default: 10000, web/pserv only)
plan	String	No	free, s (default), m, l
numInstances	Int	No	Instance count (default: 1, 0 = suspended)
healthCheckPath	String	No	Health check endpoint (web/pserv only)
preDeployCommand	String	No	Run before deploy (migrations, etc.)
staticPublishPath	String	No	Build output dir (required for static)
schedule	String	No	Cron expression (required for cron)
autoDeploy	Bool	No	Auto-deploy on push (default: true)
envVars	Array	No	Environment variables
domains	Array	No	Custom domain strings (web/static only)
disk	Object	No	Persistent disk: { name, mountPath, sizeGB }
buildFilter	Object	No	Build triggers: { paths, ignoredPaths }
image	Object	No	Prebuilt image: { url }
buildInclude	Array	No	Whitelist files for build context (.dockerignore)
buildExclude	Array	No	Exclude files from build context (.dockerignore)
baseImage	String	No	Override base image for auto-generated Dockerfile

Environment Variable Types

envVars examples

envVars:
  # Static value
  - key: NODE_ENV
    value: production

  # Auto-generated secret (32 chars)
  - key: SECRET_KEY
    generateValue: true

  # Reference a database property
  - key: DATABASE_URL
    fromDatabase:
      name: my-db
      property: connectionString  # or: host, port, user, password, database

  # Reference another service
  - key: API_HOST
    fromService:
      name: my-api
      type: web
      property: host  # or: port, hostport, connectionString

  # Copy an env var from another service
  - key: SHARED_SECRET
    fromService:
      name: my-api
      type: web
      envVarKey: SECRET_KEY

  # Import a shared env group
  - fromGroup: shared-config

Database Fields

Field	Type	Description
name	String	Database identifier (required, unique)
plan	String	free (1Gi), s (5Gi), m (20Gi), l (100Gi). Default: s
postgresMajorVersion	Int	PostgreSQL version (default: 16)
databaseName	String	Custom DB name (defaults to resource name)
user	String	Custom username (defaults to resource name)
initScript	String	Inline SQL to run once on first provision (e.g. CREATE EXTENSION IF NOT EXISTS pgcrypto)
initScriptPath	String	Path to a .sql file in the repo (relative to root). Read at sync time, run once on first provision.

Disk Configuration

disk example

services:
  - type: web
    name: my-app
    runtime: node
    disk:
      name: data
      mountPath: /var/data
      sizeGB: 10

Image Deploy

image deploy

services:
  - type: web
    name: my-app
    image:
      url: docker.io/myorg/myapp:latest
    port: 3000

Key-Value (Redis) Fields

Field	Type	Description
name	String	Redis instance identifier (required, unique)
plan	String	free (1Gi), s (2Gi), m (5Gi), l (10Gi). Default: s
maxmemoryPolicy	String	Redis eviction policy (default: allkeys-lru)

Resource Limits by Size

Size	CPU	Memory	Price
free	100m - 250m	256Mi - 512Mi	$0
s	500m - 1	512Mi - 1Gi	$0.01/hr
m	1 - 2	2Gi - 4Gi	$0.02/hr
l	2 - 4	4Gi - 8Gi	$0.04/hr

Defaults Applied

Field	Default
type	web
port	10000
plan	s
numInstances	1
autoDeploy	true
disk.sizeGB	10
postgresMajorVersion	16
maxmemoryPolicy	allkeys-lru

Build Filter

build filter example

services:
  - type: web
    name: my-api
    runtime: node
    buildFilter:
      paths:
        - src/**
        - package.json
      ignoredPaths:
        - docs/**
        - "*.md"

Per-Service Build Context (buildInclude / buildExclude)

Control which files each service sees during build. These fields accept comma-separated glob patterns in YAML array form. Patterns follow standard glob syntax (*, **, ?).

• buildInclude Whitelist -- only matching files are included in the Docker build context. All other files are excluded via .dockerignore.
• buildExclude Blacklist -- matching files are added to .dockerignore. All other files are included.

If both are set, buildInclude takes precedence. Useful for monorepos where multiple services share a directory.

buildInclude (whitelist)

services:
  # Only include specific files in the build
  - type: worker
    name: sync-worker
    runtime: python
    buildInclude:
      - worker.py
      - requirements.txt
      - schema.sql
      - lib/**          # glob: include entire lib directory

buildExclude (blacklist)

services:
  # Exclude specific files from the build
  - type: web
    name: viewer
    runtime: node
    buildExclude:
      - worker.py
      - sync.log
      - "*.md"          # glob: exclude all markdown files
      - "tests/**"      # glob: exclude test directory

Custom Base Image (baseImage)

Override the default base image for Nixpacks auto-generated Dockerfiles. This is useful when your service needs multiple runtimes (e.g., Python + Node.js) or system libraries not in the default image. The baseImage replaces the FROM line in the generated Dockerfile.

Runtime compatibility

The base image must be compatible with your chosen runtime. For runtime: node, the image must have Node.js installed. For runtime: python, Python must be available. If using runtime: docker with a custom Dockerfile, baseImage is ignored.

baseImage example

services:
  - type: web
    name: fullstack-app
    runtime: python
    baseImage: nikolaik/python-nodejs:python3.12-nodejs20
    buildCommand: pip install -r requirements.txt && npm install && npm run build
    startCommand: uvicorn api:app --host 0.0.0.0 --port $PORT

Database Init Script

Run SQL once when a managed database is first provisioned. Use initScript for short inline SQL, or initScriptPath for a full schema file from the repo. Both can be used together (inline runs first).

inline SQL

databases:
  - name: my-db
    plan: s
    initScript: CREATE EXTENSION IF NOT EXISTS pgcrypto;

SQL file from repo

databases:
  - name: my-db
    plan: s
    initScriptPath: db/schema.sql