Railway Python Bottle Quickstart

Deploy minimal Python Bottle web applications to Railway with zero configuration. This skill helps you work with the Railway Python Bottle quickstart template, optimized for fast builds and production-ready deployment.

What This Skill Does

This skill provides guidance for working with Railway's Python Bottle template repository. It helps you:

Architecture Overview

The template uses:

Core files:

Step-by-Step Instructions

1. Local Development Setup

When setting up local development:

1. Create virtual environment with uv (recommended):

```bash

uv venv --python 3.13

```

2. Activate the virtual environment:

- Linux/Mac: `source .venv/bin/activate`

- Windows: `.venv\Scripts\activate`

3. Install dependencies:

```bash

uv sync

```

2. Running Locally

For local development, choose the appropriate method:

**Development Server (built-in Bottle):**

```bash

python main.py

```

**Production-like (Gunicorn IPv4 only):**

```bash

gunicorn main:app --bind "0.0.0.0:8080"

```

**Production-like (dual-stack IPv4/IPv6, matches Railway):**

```bash

gunicorn main:app --bind 0.0.0.0:${PORT:-8080} --bind "[::]:${PORT:-8080}"

```

**Custom port:**

```bash

PORT=3000 python main.py

```

3. Railway Deployment

When deploying to Railway:

1. Use Railway CLI:

```bash

railway up

```

2. **IMPORTANT**: Railway automatically provides the `PORT` variable - never hardcode or manually set it

3. Configure optional environment variables if needed:

```bash

railway variables set LOG_LEVEL=debug

```

4. Key Design Principles

When modifying this template, preserve these design decisions:

1. **Railpack Builder**: Uses Railpack (not Nixpacks) for faster builds with uv package manager

2. **PORT Handling**: Always use Railway's auto-provided PORT variable with fallback to 8080 for local dev

3. **Dual-Stack Networking**: Gunicorn must bind to `[::]` for IPv4/IPv6 support (required for Railway)

4. **Health Checks**: `/health` endpoint must return JSON with 200 status for Railway monitoring

5. **Log Levels**: Gunicorn log level controlled via `LOG_LEVEL` environment variable (debug, info, warning, error, critical)

6. **Server Choice**: Production uses Gunicorn, local development uses Bottle's built-in server

5. Testing Changes

Before committing changes to the template:

1. Verify zero-configuration deployment capability on Railway

2. Ensure proper handling of Railway's auto-provided PORT variable (no hardcoded ports)

3. Test the `/health` endpoint returns 200 status

4. Confirm local development works when PORT is not provided (fallback to 8080)

5. Test both local dev server and Gunicorn modes

6. Adding New Routes

When extending the application:

1. Add new routes in `main.py` using Bottle's `@route()` decorator

2. Maintain the existing `/health` endpoint for Railway monitoring

3. Follow the pattern of returning HTML for user-facing routes, JSON for API endpoints

4. Use `os.getenv()` for configuration with sensible defaults

7. Environment Variables

Available environment variables:

When adding new environment variables:

Examples

Adding a New API Endpoint

```python

@route('/api/status')

def api_status():

response.content_type = 'application/json'

return json.dumps({

'status': 'operational',

'version': '1.0.0'

})

```

Adding Environment Configuration

```python

import os

DEBUG_MODE = os.getenv('DEBUG', 'false').lower() == 'true'

API_KEY = os.getenv('API_KEY', '')

@route('/api/data')

def api_data():

if not API_KEY:

abort(500, 'API_KEY not configured')

# ... rest of logic

```

Constraints