Deploy a Python uv Project with Git and Railpack in Dokploy

You can deploy a Python uv project in Dokploy with Railpack as the build provider. No Dockerfile needed. Push to Git, and Dokploy builds and serves your app automatically via Docker and Traefik.

This guide covers a FastHTML app from project init with uv, through Railpack’s zero-config detection, to port configuration (the part that trips most people up) and the failure modes you’ll hit. If you’re new to uv, check the Getting Started with uv guide. For FastHTML basics, see FastHTML for Beginners. If Dokploy isn’t installed yet, follow the Dokploy installation guide first.

Dokploy’s core is Apache-2.0 (free to self-host). A managed Dokploy Cloud option exists from $4.50/mo per server if you’d rather not maintain it yourself.

What are Dokploy, Railpack, and uv?

uv is a Rust-based Python package manager from Astral. It’s 10 to 100x faster than pip at resolving and installing dependencies, and it replaces pip, Poetry, pyenv, and virtualenv. It uses pyproject.toml for configuration and uv.lock for reproducible installs. If you’re picking from the best Python web frameworks, uv works with all of them.

Railpack is a build provider from the Railway team. It auto-detects your project type, installs dependencies, and produces a deployable container. For Python, Railpack recognizes projects when files like main.py, app.py, pyproject.toml, or requirements.txt exist at the repo root. When it finds both pyproject.toml and uv.lock, it uses uv as the package manager automatically.

Dokploy is a self-hosted deployment platform (around 36.7k GitHub stars) that orchestrates Docker containers with Traefik for routing. It supports Git-based deploys and multiple build types: Railpack, Nixpacks, and Dockerfile. It’s one of the best self-hosted server panels if you want PaaS convenience without giving up control. Core is Apache-2.0; future paid features are source-available. Dokploy Cloud starts at $4.50/mo/server (Hobby tier).

Step-by-step: deploy a Python uv project with Railpack in Dokploy

Deploy a FastHTML app from scratch. The flow is: create the project, push to Git, configure Dokploy, deploy.

Prerequisites

Note on uv versions: Starting with uv 0.12.0 (July 2026), uv init creates a packaged project layout by default (source under src/, a build system, entry points). We’ll use uv init --no-package to get the flat layout that Railpack expects at the repo root.

Step 1: set up your uv-managed Python project

Initialize a project with the flat (no-package) layout, then add FastHTML:

uv init --no-package my-fasthtml-app
cd my-fasthtml-app
uv add python-fasthtml

This gives you:

my-fasthtml-app/
├── .python-version  # e.g., "3.12"
├── main.py          # Entry point
├── pyproject.toml   # Project config
├── uv.lock          # Locked dependencies
└── README.md

Note: you don’t need to manually create a virtualenv or run source .venv/bin/activate. uv handles this automatically when you use uv add or uv run.

Write a minimal FastHTML app in main.py:

from fasthtml.common import *

app, rt = fast_app()

@rt("/")
def get():
    return Div(P("Hello from uv and Dokploy!"))

serve()

Test locally:

uv run main.py

Visit http://localhost:5001 to verify it works. The serve() function binds port 5001 locally. This is for development only. In production, Railpack uses a different start command (covered in Step 2).

Push to Git:

git init
git add .
git commit -m "initial commit"
git branch -M main
git remote add origin [email protected]:user/my-fasthtml-app.git
git push -u origin main

Step 2: understand Railpack’s auto-detection

For a basic uv + FastHTML project, you don’t need a railpack.json. Zero config. Here’s what Railpack does automatically:

Detection: Railpack recognizes Python projects when any of these files exist at the repo root: main.py, app.py, start.py, bot.py, hello.py, server.py, requirements.txt, pyproject.toml, or Pipfile.

Package manager selection: When both pyproject.toml and uv.lock are present, Railpack uses uv to install dependencies.

Python version resolution (in priority order):

1. RAILPACK_PYTHON_VERSION environment variable
2. .python-version, .tool-versions, or mise.toml
3. runtime.txt
4. Pipfile
5. Default: 3.13.2

FastHTML start command: When Railpack detects python-fasthtml as a dependency and uvicorn is available (it is, FastHTML depends on it), it starts the app with:

uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}

Runtime variables Railpack sets automatically: PYTHONUNBUFFERED=1, PYTHONFAULTHANDLER=1, PYTHONHASHSEED=random, PYTHONDONTWRITEBYTECODE=1, PIP_DISABLE_PIP_VERSION_CHECK=1, PIP_DEFAULT_TIMEOUT=100.

Optional: custom railpack.json

If you need to override the start command or add build-time packages, create a railpack.json at the repo root:

{
  "$schema": "https://schema.railpack.com",
  "provider": "python",
  "deploy": {
    "startCommand": "uvicorn main:app --host 0.0.0.0 --port 8000"
  }
}

For most uv + FastHTML projects, skip this file entirely.

Step 3: set up Dokploy with Git (port = 8000)

Deploy using Dokploy’s Git integration with Railpack as the build type.

1. Log in to Dokploy. Open your dashboard (e.g., http://your-server-ip:3000).

2. Create a new project. Go to Projects > New Project, name it my-uv-app, and save.

3. Add an application. Inside the project, you’ll see a default production environment (Dokploy introduced Environments in v0.25.0). Add a new application:

   • Name: my-uv-app
   • Git Repository: https://github.com/yourusername/my-fasthtml-app.git
   • Branch: main
   • Build Type: Railpack
   • Save.

4. Set the port to 8000. In the application settings, set the port field to 8000. This matches Railpack’s ${PORT:-8000} default for FastHTML apps. Dokploy uses Traefik as a reverse proxy to route traffic. If the port doesn’t match what the container listens on, you’ll get 502 errors.

5. Set up a domain. In the Domains tab, add your custom domain (e.g., my-uv-app.yourdomain.com). Make sure the port matches (8000). Enable HTTPS. Dokploy handles the Traefik routing and certificate generation automatically.

6. Add environment variables (optional). In the Environment tab, add any env vars your project needs.

7. Deploy. Click Deploy. Dokploy clones the repo, Railpack builds the image, and the container starts.

Step 4: verify the deployment

1. Check build logs. In the Logs tab, look for uv sync (install step) followed by Uvicorn running on http://0.0.0.0:8000.

2. Test the app. Visit your URL (e.g., https://my-uv-app.yourdomain.com). You should see the FastHTML response: <div><p>Hello from uv and Dokploy!</p></div>.

3. If you get 502/504, the port is almost certainly wrong. Go back to Step 3 and verify the port is set to 8000. See the Troubleshooting section below for more failure modes.

Step 5: automate future deployments

1. Enable auto-deploy. In the application settings, enable Auto Deploy for the main branch.
2. Push an update. Edit main.py:

@rt("/")
def get():
    return Div(P("Updated: Hello from uv and Dokploy!"))

git add main.py
git commit -m "update greeting"
git push origin main

Dokploy detects the push and redeploys automatically.

Railpack vs Nixpacks vs Dockerfile: which build type?

Dokploy supports five build types. Here’s how to choose for a Python project:

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

For a comparison of Dokploy with other platforms, see Coolify vs Dokploy vs Kamal 2.

FastHTML deployment notes: ports and start command

The local-vs-production port difference is the most common source of confusion:

• Locally: serve() in main.py binds port 5001. This is for development.
• In production: Railpack detects FastHTML and runs uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}. The serve() call never executes because uvicorn imports the module directly. Port 8000 is the production default.

If you need a different production port, set the PORT environment variable in Dokploy’s Environment tab, or override the start command in railpack.json.

uvicorn is available at runtime because python-fasthtml depends on it — you don’t need to add it separately.

Troubleshooting Dokploy + Railpack deploys

Why use Dokploy with uv and Railpack?

For updating your deployed apps, see how to update Docker Compose stacks in Dokploy.

Conclusion

Deploy a Python uv project in Dokploy with Railpack and the flow is: uv init --no-package → add your framework → push to Git → Dokploy + Railpack build and deploy automatically. Set port 8000 in the domain config, and you’re live. No Dockerfile needed.

This is a zero-config path for Python self-hosting. For more control over build layers, base images, or system dependencies, a Dockerfile or Docker Compose is the next step — see how to update Docker Compose stacks in Dokploy for that workflow.

Pin your Railpack version, commit your uv.lock, and verify the port. Those three things prevent 90% of deployment failures.