Hostless File

The Hostless file (hostless.yaml) is a configuration file that allows you to define and manage your application's infrastructure as code. It provides a declarative way to configure build settings, deployment parameters, scaling rules, health checks, cron jobs, and worker processes - all from a single configuration file in your repository.

Overview

The Hostless file enables you to:

• Version control your infrastructure: Keep your application configuration alongside your code
• Automate deployments: Changes to the hostless file trigger automatic updates to your app configuration
• Ensure consistency: Define your infrastructure once and apply it consistently across environments
• Simplify app management: Configure all aspects of your app from a single file

File Location

By default, Hostless looks for a file named hostless.yaml in the root of your repository. You can customize the file path in your app settings if needed.

File Format

The Hostless file uses YAML format for configuration. Here's the complete structure:

# Build Configuration
build:
  command: "npm install && npm run build"  # Command to build your application
  system: auto                             # Build system: 'auto', 'docker', or 'nixpacks'
  min_cpu: 0.5                            # Minimum CPU allocated for builds
  max_cpu: 2                              # Maximum CPU allocated for builds
  min_memory: 512                         # Minimum memory in MB for builds
  max_memory: 2048                        # Maximum memory in MB for builds

# Docker Configuration (optional)
dockerfile_path: "./Dockerfile"           # Path to Dockerfile if using Docker build system

# Post-Build Command (optional)
post_build_command: "npm run migrate"     # Command to run after build, before deployment

# Start Command
start_command: "npm start"                # Command to start your application

# Scaling Configuration
scaling:
  trigger: http_requests                  # Scaling trigger type
  min_cpu: 0.1                           # Minimum CPU per replica
  max_cpu: 1                              # Maximum CPU per replica
  min_memory: 128                         # Minimum memory in MB per replica
  max_memory: 1024                        # Maximum memory in MB per replica
  min_replicas: 1                         # Minimum number of replicas
  max_replicas: 5                         # Maximum number of replicas
  max_http_requests_per_replica: 100     # Max concurrent requests per replica

# Health Check Configuration
health_check:
  type: http                              # Health check type: 'http', 'tcp', or 'command'
  http_path: "/health"                    # HTTP path for health checks (if type is http)
  interval_in_seconds: 30                 # Interval between health checks

# Cron Jobs (optional)
cron_jobs:
  - command: "npm run cleanup"            # Command to execute
    schedule: "0 0 * * *"                 # Cron expression (daily at midnight)
    timezone_utc_offset: 0                # UTC offset for timezone
    cpus: 0.5                             # CPU allocation for the job
    memory: 256                           # Memory allocation in MB
    status: "active"                      # Job status: 'active' or 'inactive'

# Worker Processes (optional)
workers:
  - name: "queue-processor"              # Unique name for the worker
    command: "npm run worker:queue"      # Command to run the worker
    min_cpu_per_replica: 0.1            # Minimum CPU per worker replica
    max_cpu_per_replica: 1              # Maximum CPU per worker replica
    min_memory_per_replica: 128         # Minimum memory in MB per replica
    max_memory_per_replica: 512         # Maximum memory in MB per replica
    replicas: 2                          # Number of worker replicas

Configuration Sections

Build Configuration

The build section defines how your application is built:

Field	Type	Description	Required
command	string	Build command to execute	No
system	string	Build system: auto, docker, or nixpacks	No
min_cpu	number	Minimum CPU cores for build (0.01 - 16)	No
max_cpu	number	Maximum CPU cores for build (0.1 - 16)	No
min_memory	number	Minimum memory in MB (128 - 32768)	No
max_memory	number	Maximum memory in MB (128 - 32768)	No

Deployment Configuration

Field	Type	Description	Required
dockerfile_path	string	Path to Dockerfile (when using Docker build)	No
post_build_command	string	Command to run after build, before deployment	No
start_command	string	Command to start your application	No

Scaling Configuration

The scaling section controls how your application scales:

Field	Type	Description	Required
trigger	string	Scaling trigger: http_requests	No
min_cpu	number	Minimum CPU per replica (0.01 - 16)	No
max_cpu	number	Maximum CPU per replica (0.1 - 16)	No
min_memory	number	Minimum memory in MB per replica	No
max_memory	number	Maximum memory in MB per replica	No
min_replicas	number	Minimum number of replicas (1+)	No
max_replicas	number	Maximum number of replicas (1+)	No
max_http_requests_per_replica	number	Max concurrent requests per replica	No

Health Check Configuration

Field	Type	Description	Required
type	string	Health check type: http, tcp, or command	No
http_path	string	HTTP endpoint path (when type is http)	No
interval_in_seconds	number	Seconds between health checks	No

Cron Jobs

Each cron job in the cron_jobs array supports:

Field	Type	Description	Required
command	string	Command to execute	Yes
schedule	string	Cron expression	Yes
timezone_utc_offset	number	UTC offset (-12 to +14)	Yes
cpus	number	CPU allocation (0.01 - 16)	No
memory	number	Memory allocation in MB	No
status	string	Job status: active or inactive	No

Worker Processes

Each worker in the workers array supports:

Field	Type	Description	Required
name	string	Unique worker name	Yes
command	string	Command to run the worker	Yes
min_cpu_per_replica	number	Minimum CPU per replica	Yes
max_cpu_per_replica	number	Maximum CPU per replica	Yes
min_memory_per_replica	number	Minimum memory in MB	Yes
max_memory_per_replica	number	Maximum memory in MB	Yes
replicas	number	Number of replicas	Yes

How It Works

Automatic Sync on Deployment

When you push changes to your repository, Hostless automatically:

1. Detects if a hostless.yaml file exists in your repository
2. Validates the configuration
3. Applies the configuration to your app
4. Updates build settings, scaling rules, health checks, cron jobs, and workers accordingly

Examples

Basic Node.js Application

build:
  command: "npm install"
  system: auto
  min_cpu: 0.5
  max_cpu: 2
  min_memory: 512
  max_memory: 2048

start_command: "node server.js"

scaling:
  min_replicas: 1
  max_replicas: 3
  min_cpu: 0.1
  max_cpu: 1
  min_memory: 256
  max_memory: 1024

health_check:
  type: http
  http_path: "/health"
  interval_in_seconds: 30

Python Application with Workers and Cron Jobs

build:
  command: "pip install -r requirements.txt"
  system: auto
  min_cpu: 1
  max_cpu: 4
  min_memory: 1024
  max_memory: 4096

post_build_command: "python manage.py migrate"
start_command: "gunicorn app:application --bind 0.0.0.0:$PORT"

scaling:
  trigger: http_requests
  min_replicas: 2
  max_replicas: 10
  min_cpu: 0.5
  max_cpu: 2
  min_memory: 512
  max_memory: 2048
  max_http_requests_per_replica: 50

health_check:
  type: http
  http_path: "/api/health"
  interval_in_seconds: 20

cron_jobs:
  - command: "python manage.py cleanup_old_data"
    schedule: "0 2 * * *"
    timezone_utc_offset: 0
    cpus: 1
    memory: 512
    status: active

workers:
  - name: "celery-worker"
    command: "celery -A app worker -l info"
    min_cpu_per_replica: 0.5
    max_cpu_per_replica: 2
    min_memory_per_replica: 512
    max_memory_per_replica: 2048
    replicas: 3
  - name: "celery-beat"
    command: "celery -A app beat -l info"
    min_cpu_per_replica: 0.1
    max_cpu_per_replica: 0.5
    min_memory_per_replica: 256
    max_memory_per_replica: 512
    replicas: 1

Docker-based Application

build:
  system: docker
  min_cpu: 2
  max_cpu: 8
  min_memory: 2048
  max_memory: 8192

dockerfile_path: "./Dockerfile"
start_command: "docker-entrypoint.sh"

scaling:
  min_replicas: 1
  max_replicas: 5
  min_cpu: 1
  max_cpu: 4
  min_memory: 1024
  max_memory: 4096

health_check:
  type: tcp
  interval_in_seconds: 15

Best Practices

1. Start Simple: Begin with minimal configuration and add complexity as needed
2. Version Control: Always commit your hostless.yaml file to your repository
3. Test Locally: Validate your YAML syntax before committing
4. Resource Limits: Set appropriate min/max values to control costs while ensuring performance
5. Health Checks: Configure health checks to ensure your app stays healthy
6. Environment Variables: Keep sensitive data in environment variables, not in the hostless file

Validation

Hostless automatically validates your configuration file for:

• Valid YAML syntax
• Required fields
• Value ranges (CPU, memory, replicas)
• Cron expression validity
• Unique worker names

If validation fails, the deployment will be rejected with detailed error messages.

Troubleshooting

Common Issues

Validation Errors

• Check YAML syntax using a validator
• Ensure all required fields are present
• Verify values are within acceptable ranges

Configuration Not Applied

• Check deployment logs for errors
• Ensure you have proper permissions
• Verify the file is committed to the correct branch

Workers Not Starting

• Ensure worker commands are correct
• Check worker logs for errors
• Verify resource allocations are sufficient

Related Documentation

• Deployments - Learn about the deployment process
• Scaling Configuration - Detailed scaling options
• Build Configuration - Build system details
• Workers - Managing worker processes
• Cron Jobs - Scheduling tasks
• Health Checks - Monitoring app health