---
title: "Deploying a Python uv Project with Git and Railpack in Dokploy"
description: "See how you can host your project easily with Dokploy, Railpack, and uv"
date: 2025-03-12
categories: ["vps"]
tags: ["dokploy","uv","python"]
---

Dokploy is an open-source platform that simplifies deploying applications on your VPS using Docker and Traefik. With its Git integration and support for Railpack—a versatile build provider—you can deploy Python projects managed with uv effortlessly. In this guide, we’ll deploy a FastHTML-based Python project using Git and Railpack within Dokploy, detailing the project setup, Railpack configuration with railpack.json, and deployment steps.

In the past I have covered [dokploy installation](https://www.bitdoze.com/dokploy-install/) and [uv get started](https://www.bitdoze.com/uv-get-started/) + [fasthtml get started](https://www.bitdoze.com/fasthtml-start/), you can check them for more details on each.


Dokploy, Railpack, and uv form a powerful stack for self-hosted Python deployments. Let’s get started!

## What Are uv, Railpack, and Dokploy?

### uv
[uv](https://docs.astral.sh/uv/), developed by Astral, is a Rust-based Python package and project manager that outperforms tools like `pip` and `poetry`. It’s 10-100x faster at resolving and installing dependencies, using a `uv.lock` file for reproducibility and `pyproject.toml` for configuration.

### Railpack
[Railpack](https://railpack.com/) builds and deploys applications, supporting Python with package managers like uv. It detects Python projects via files such as main.py or pyproject.toml, installs dependencies, and configures a production environment using a railpack.json file if provided.

### Dokploy
[Dokploy](https://dokploy.com/) is a self-hosted deployment solution that orchestrates applications via Docker, with Traefik for routing and load balancing. It supports Git-based deployments and multiple build types, including Railpack, allowing you to push code to a repository and have Dokploy build and deploy it automatically.

## Deploying a Python uv Project with Git and Railpack in Dokploy


<YouTubeEmbed
  url="https://www.youtube.com/embed/652DqHl7Ppo"
  label="Deploying a Python uv Project with Git and Railpack in Dokploy"
/>

### Prerequisites

Before starting, ensure you have:
- **Dokploy** installed on a VPS (follow the [installation guide](https://www.bitdoze.com/dokploy-install/)).
- **uv** installed locally (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
- **Git** installed locally and a Git repository (e.g., GitHub, GitLab).
- **Docker** running on your Dokploy server (included by default).
- Access to your Dokploy dashboard (e.g., `http://your-server-ip:3000`).

We’ll deploy a FastHTML app as an example.



### Step 1: Set Up Your uv-Managed Python Project

Create a Python project with `uv` and FastHTML.

1. **Initialize the Project**
   ```bash
   uv init my-fasthtml-app
   cd my-fasthtml-app
   ```
   This generates:
   ```
   my-fasthtml-app/
   ├── .python-version  # e.g., "3.12"
   ├── main.py         # Starter script
   ├── pyproject.toml  # Project config
   └── README.md       # Documentation
   ```

2. **Add Dependencies**
   Install FastHTML:
   ```bash
   uv venv
   source .venv/bin/activate
   uv add python-fasthtml
   ```
   This updates `pyproject.toml` and creates a `uv.lock` file.

3. **Write a FastHTML App**
   Edit `main.py`:
   ```python
   from fasthtml.common import *

   app, rt = fast_app()

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

   serve()
   ```

4. **Test Locally**
   ```bash
   uv run main.py
   ```
   Visit `http://localhost:5001` to verify it works.

5. **Initialize Git**
   ```bash
   git init
   git add .
   git commit -m "first commit"
   git branch -M main
   git remote add origin git@github.com:user/my-fasthtml-app.git
   git push -u origin main
   ```


### Step 2: Configure Railpack for Dokploy

Railpack detects Python projects via `main.py`, `pyproject.toml`, or `uv.lock` and supports `uv` natively. You don't need to do anything but `railpack.json` file can be used to customize the build and deployment for more advanced configurations.

 **Understand Railpack Defaults**
   - **Detection**: Recognizes `main.py`, `pyproject.toml`, and `uv.lock`.
   - **Versions**: Defaults to Python 3.13.2, overridable with `.python-version` or `RAILPACK_PYTHON_VERSION`.
   - **Install**: For `uv.lock`, Railpack uses `uv` to install dependencies (assumed to be `uv sync`).
   - **Start**: Defaults to `python main.py` if no framework is detected.
   - **Runtime**: Sets variables like `PYTHONUNBUFFERED=1`.



### Step 3: Set Up Dokploy with Git

Deploy using Dokploy’s Git integration and Railpack.

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**
   - Click **New Application**.
   - **Name**: `my-uv-app`.
   - **Git Repository**: `https://github.com/yourusername/my-uv-app.git`.
   - **Branch**: `main`.
   - **Build Type**: **Railpack** (select custom if Railpack isn’t listed).
   - Save.

![dokploy project](@images/25/03/dokploy-project.png)



4. **Configure Environment Variables (Optional)**
   - In the **Environment** tab, add what env varialbes you need for your project.

5. **Set Up a Domain**
   - In the **Domains** tab, add a custom domain (e.g., `my-uv-app.yourdomain.com`) be sure the domain is properly configured.
   - Enable HTTPS for custom domains.

![dokploy domamain](@images/25/03/dokploy-domain.png)

6. **Deploy the Application**
   - Click **Deploy**.
   - Dokploy clones the repo, uses Railpack  to build, and deploys the container.


### Step 4: Verify the Deployment

1. **Check the Logs**
   - In the **Logs** tab, confirm `uv sync` and the app starting.

2. **Test the App**
   - Visit your URL (e.g., `http://my-uv-app-yourserver.dokploy.app`).
   - Expect: `<div><p>Hello from uv and Dokploy!</p></div>`.



### Step 5: Automate Future Deployments

1. **Enable Auto-Deploy**
   - In settings, enable **Auto Deploy** for `main`.
   - Push updates to trigger redeployments.

2. **Example Update**
   Edit `main.py`:
   ```python
   @rt("/")
   def get():
       return Div(P("Updated: Hello from uv and Dokploy!"))
   ```
   ```bash
   git add main.py
   git commit -m "Update greeting"
   git push origin main
   ```



## Why Use Dokploy with uv and Railpack?

- **Self-Hosted Flexibility**: Running Dokploy on your own VPS gives you full control over your infrastructure, avoiding the constraints and costs of managed cloud platforms. You dictate the hardware, security policies, and scaling options, making it ideal for privacy-conscious projects or custom setups.
- **Speed and Efficiency**: `uv`’s lightning-fast dependency resolution—often 10-100x quicker than `pip`—pairs perfectly with Railpack’ streamlined build process, reducing deployment times significantly. This combination minimizes downtime and accelerates iteration cycles, crucial for rapid development and testing.
- **Automation and Workflow Integration**: Git-driven deployments through Dokploy enable a seamless CI/CD pipeline. Push changes to your repository, and Dokploy automatically rebuilds and redeploys your app using Railpack, eliminating manual intervention. This automation integrates effortlessly with existing Git workflows, enhancing team productivity.
- **Reproducibility**: `uv`’s `uv.lock` ensures consistent dependency versions across environments, while Railpack’ configuration in `railpack.json` locks in build and runtime steps. Together, they guarantee your app behaves the same locally and in production, reducing “works on my machine” issues.
- **Modern Tooling Synergy**: In 2025, `uv` and Railpack represent cutting-edge Python tooling, leveraging Rust’s performance and modern build practices. Dokploy ties these together with a user-friendly interface, making advanced deployment accessible without sacrificing power.



## Conclusion

Deploying a `uv`-managed FastHTML project with Git and Railpack in Dokploy offers an efficient, customizable, and forward-thinking approach to Python application hosting. The `railpack.json` configuration lets you precisely define how your project is built and run, from installing `uv` and syncing dependencies to launching your FastHTML app. By pushing your code to a Git repository and configuring Dokploy, your application goes live on your own infrastructure in minutes—self-hosted, secure, and poised for growth.

This stack not only simplifies deployment but also empowers you with the tools to iterate quickly, scale confidently, and maintain full ownership of your environment. Whether you’re building a small prototype or a production-ready service, Dokploy, `uv`, and Railpack deliver a modern deployment experience tailored to 2025’s demands.

For updating your deployed apps, see our guide on [How to Update Docker Compose Stacks in Dokploy](https://www.bitdoze.com/dokploy-update-docker-compose/).