DEV Community: Andreas M

Self-Hosted Deployment Tools Compared: Coolify, Dokploy, Kamal, Dokku, and Haloy

Andreas M — Tue, 10 Feb 2026 07:37:42 +0000

The self-hosted deployment space has grown significantly over the past few years. Developers who want to deploy to their own servers without Kubernetes complexity or expensive PaaS bills now have real options. But the tools take very different approaches, and picking the wrong one means either fighting the tool or migrating later.

This post compares five popular self-hosted deployment tools. I'll cover what each one does well, where each falls short, and who each is best suited for.

The Quick Summary

Before going deep, here's a high-level overview:

	Approach	Language	Interface	Multi-Server	Docker Registry Required
Coolify	Self-hosted PaaS	PHP	Web GUI	Yes	No
Dokploy	Self-hosted PaaS	TypeScript	Web GUI	Yes	No
Kamal	CLI deployment tool	Ruby	CLI only	Yes	Yes
Dokku	Mini-Heroku	Go	CLI only	No	No
Haloy	CLI deployment tool	Go	CLI only	Yes	Optional

The tools break down along two main axes: GUI vs. CLI, and full platform vs. focused tool.

Coolify

Coolify is the most popular self-hosted PaaS option right now, with over 50,000 GitHub stars. It positions itself as a self-hosted alternative to Vercel, Netlify, and Heroku. You install it on a server, and it gives you a polished web dashboard to manage applications, databases, and services.

What it does well:

Coolify has the richest feature set of any tool on this list. It offers 280+ one-click application templates (Supabase, Plausible, n8n, and more), built-in database management with automated backups, Git integration for deploying from GitHub or GitLab, and monitoring via Grafana. It supports Docker Compose natively and can manage multiple servers. If you want a single pane of glass to manage everything on your infrastructure, Coolify is the most complete option.

The community is large and active, with releases roughly every few days and hundreds of contributors.

Where it falls short:

The web UI, despite being the core selling point, gets mixed reviews. Managing complex setups can feel clunky. The platform consumes meaningful resources on your server just to run the dashboard and its dependencies, which matters on smaller VPS instances. Scaling is limited to Docker Swarm, with no Kubernetes path. Database restores require SSH access and manual commands rather than a dashboard button.

Security has also been a concern. An independent audit identified seven CVEs in the platform, which is worth considering for production workloads.

Best for: Teams that want a Vercel-like experience on their own infrastructure and prefer managing everything through a web dashboard.

Dokploy

Dokploy is a newer self-hosted PaaS that competes directly with Coolify. It's built on Docker and Traefik, with a focus on clean design and Docker-native workflows.

What it does well:

Dokploy's UI is frequently cited as cleaner and more intuitive than Coolify's. It has strong monitoring capabilities built in, showing CPU, memory, storage, and network metrics in real-time. The API is well-documented with Swagger/OpenAPI specs and proper JWT authentication, making it easier to build automations around. Docker Compose and Docker Swarm support are first-class. It also supports multiple deployment methods: Nixpacks, Heroku Buildpacks, and custom Dockerfiles.

Where it falls short:

Dokploy is a younger project with a smaller community (roughly 24,000 GitHub stars, about half of Coolify's). The one-click app template library is smaller. Because it's newer, there's less documentation, fewer tutorials, and fewer community answers to draw from. Like Coolify, it's a heavy platform that consumes server resources to run.

Best for: Teams that want a web-based PaaS like Coolify but prefer a cleaner interface and stronger Docker-native workflows.

Kamal

Kamal is the deployment tool built by 37signals, the company behind Basecamp, HEY, and Ruby on Rails. It deploys Docker containers to any server via SSH, configured through a YAML file. No web dashboard, no server-side daemon, no platform overhead.

What it does well:

Kamal's biggest strength is its zero-overhead approach. There is nothing running on your server except your application and a small reverse proxy (kamal-proxy). No dashboards, no databases for the platform itself, no background processes consuming resources. It connects via SSH, pulls your Docker image, and does a zero-downtime swap.

The tool is battle-tested at scale. 37signals runs HEY (their email service with hundreds of thousands of users) entirely on Kamal. It ships bundled with Rails 8 as the default deployment option.

Multi-server deployments work well. You define your servers in YAML and Kamal deploys to all of them. Rolling deploys, canary deployments, and maintenance mode are all built in.

Where it falls short:

Kamal requires a Docker registry. Your CI or local machine builds an image, pushes it to a registry (Docker Hub, GitHub Container Registry, etc.), and then Kamal tells the servers to pull it. This is fine if you already have a registry workflow, but it's an extra moving part if you don't.

Installation requires Ruby, which is a non-issue for Rails teams but adds friction for Go, Python, or Node.js developers who don't have Ruby in their toolchain.

There's no built-in monitoring, log aggregation, or database management. You handle all operational concerns yourself.

Best for: Developers who want maximum control with minimum overhead, particularly Rails teams.

Dokku

Dokku is the veteran of this list, first released in 2013. It's a "mini Heroku" that gives you git-push deployments on a single server. Push your code, Dokku builds it with Heroku buildpacks or a Dockerfile, and runs it in a Docker container.

What it does well:

Dokku has the lowest barrier to entry. Install it on a fresh Ubuntu server, add a git remote, and git push dokku main. That's the entire workflow. The Heroku-compatible approach means existing buildpacks handle most language runtimes automatically. No Dockerfile needed unless you want one.

After 13 years, Dokku is stable and well-documented. The documentation is some of the best in this space. The plugin ecosystem covers databases, caching, SSL, and more. Resource usage is minimal since there's no web dashboard consuming memory.

Where it falls short:

The biggest limitation is that Dokku is single-server only. There is no built-in way to deploy to multiple servers or do horizontal scaling across machines. If your application outgrows a single server, you need to migrate to a different tool.

There's no multi-user support or role-based access control. The plugin ecosystem, while large, has quality variance, with some plugins well-maintained and others abandoned.

Best for: Solo developers running personal projects, side projects, or small production workloads that fit on a single server. If you love the Heroku workflow and want it on a cheap VPS, Dokku is the obvious choice.

Haloy

Haloy takes a different approach from both the PaaS tools and the SSH-based tools. It's a CLI that communicates with a lightweight server daemon over HTTPS. You configure your application with a YAML file, run haloy deploy, and it builds a Docker image locally, uploads only the changed layers to the server, and does a zero-downtime swap.

What it does well:

The direct-upload approach eliminates the need for a Docker registry. Haloy builds your image locally, checks which Docker layers the server already has cached, and only uploads the missing ones. After the first deploy, subsequent deploys typically transfer a fraction of the full image size. This makes the deploy workflow simpler: there's no registry to configure, no credentials to manage, no intermediate storage.

That said, Haloy also supports Docker registries if you prefer that workflow. You can build and push your image elsewhere (in CI, for example) and use haloy deploy to trigger the server to pull from the registry instead.

Configuration is a single YAML file in your project root. Automatic HTTPS via Let's Encrypt, built-in health checks, rolling deployments, instant rollbacks, and secret management (including 1Password integration) are included. Multi-server deployments are supported natively.

The server daemon means the server can actively monitor your containers, handle health checks, auto-recover crashed containers, and serve as a reverse proxy, all without external dependencies. The CLI works well with AI coding assistants, with agent skills for generating Dockerfiles and deployment configuration.

Where it falls short:

Haloy is the newest tool on this list, which means the smallest community, fewest tutorials, and least battle-testing in production. There's no web dashboard, so everything is done through the CLI. The server daemon, while lightweight, is an additional process running on your server that needs to be maintained and updated.

Best for: Developers who want simple Docker deployments to their own servers without the overhead of a full PaaS or the requirement of a Docker registry. Particularly well-suited for indie developers, small teams, and anyone who prefers a CLI-first workflow with minimal configuration.

How to Choose

If you want a web dashboard, choose between Coolify (most features, biggest community) and Dokploy (cleaner UI, better monitoring). Both give you a Vercel-like experience on your own hardware.

If you want a CLI tool, the choice depends on your workflow:

Already using a Docker registry? Kamal is a strong choice, especially for Rails teams. Zero server overhead, battle-tested at 37signals scale.
Want the simplest possible setup? If your app fits on a single server, Dokku's git-push workflow is hard to beat.
Want Docker deploys with or without a registry? Haloy lets you upload images directly with layer caching, or pull from a registry if you already have one.

If you're a solo developer running side projects on a single VPS, Dokku or Haloy give you the most straightforward path. Dokku if you prefer git-push, Haloy if you prefer explicit deploy commands with YAML config.

If you're a small team that needs multi-server deployments, Coolify, Kamal, or Haloy are the practical options. Coolify if you want a dashboard, Kamal or Haloy if you prefer CLI workflows.

What About Managed Platforms?

Tools like Fly.io, Railway, and Render compete for the same audience but with a different trade-off: convenience in exchange for recurring platform fees and vendor lock-in.

The self-hosted tools in this post all share one advantage over managed platforms: you control the infrastructure, you own the data, and your costs scale with the hardware, not with the platform's pricing model. A $10/month VPS can run a surprising amount of production workload when there's no platform overhead eating into your resources.

Final Thoughts

There's no single "best" deployment tool. Coolify and Dokploy are building toward a full PaaS experience on your own servers. Kamal and Haloy are building focused deployment tools that do one thing well. Dokku has been quietly reliable for over a decade.

The good news is that all of these tools are open source and free to use. Try a couple, see which workflow clicks, and go with that. The migration cost between them is low since they all run Docker containers at the end of the day.

Links:

LLM-First Approach to Self-Hosting with Haloy

Andreas M — Fri, 30 Jan 2026 08:29:56 +0000

I've been deploying apps and websites to servers I own or rent since the late nineties. A lot has changed over the years, but one thing has stayed the same: it's tedious work.

The last decade has been all about Docker, and that has made things more stable and reproducible, but the setup and deployment process hasn't gotten any better. It was actually simpler a couple of decades ago. Now it's SSH in, install Docker, write a Dockerfile, figure out nginx configs for SSL, debug why the proxy isn't working, and eventually get something running.

Every project feels like reinventing the wheel.

What if your AI coding assistant could handle deployment config?

That's the idea behind Haloy and its agent skills. Haloy is a deployment tool for self-hosting. Think docker-compose, but for production. You write a haloy.yaml, run haloy deploy, and your app is live with automatic HTTPS.

The interesting part is the agent skills. These are packaged instructions that teach AI coding assistants (Claude Code, Cursor, etc.) how to prepare your app for deployment.

Two skills, two steps

Install the skills with:

npx skills add haloydev/agent-skills

Step 1: Dockerize your app

First, you need a Dockerfile. The dockerize skill handles this. In Claude Code, I use the /dockerize command. Other tools might trigger it differently, but the idea is the same: tell your assistant to dockerize the project.

It will:

Detect your framework (Tanstack Start, Next.js, FastAPI, Go, whatever)
Create a multi-stage Dockerfile with the right base image
Add a health check endpoint if you don't have one
Generate a proper .dockerignore

Step 2: Create the Haloy config

Once you have a Dockerfile, use the haloy-config skill. In Claude Code, I use /haloy-config. It will:

Figure out which port your app runs on
Ask which of your configured servers to deploy to
Ask for your domain
Generate a working haloy.yaml

What this actually looks like

You're in your project directory with a TanStack Start app. You run /dockerize in Claude Code. It reads your package.json, creates a Dockerfile with Node 24, and adds a /health route.

Then you run /haloy-config. It asks for your server and domain, and generates haloy.yaml.

Run haloy deploy and you're live.

The VPS setup

On the server side, it's one command:

curl -fsSL https://sh.haloy.dev/install-haloyd.sh | API_DOMAIN=haloy.yourserver.com sh

This installs the Haloy daemon and gives you a token. Add the server to your local CLI with haloy server add, and you're done.

Why this matters

Self-hosting shouldn't require deep DevOps knowledge for every project. But the tooling has always assumed you know what you're doing.

LLM coding assistants are good at following instructions. Agent skills give them the right instructions for deployment. You get the benefits of self-hosting (control, cost, no vendor lock-in) without the setup friction.

Links:

Deploy TanStack Start + PostgreSQL to Your Own Server with Haloy

Andreas M — Tue, 06 Jan 2026 11:49:27 +0000

Deploy a production-ready TanStack Start application with PostgreSQL to your own server in minutes. No Kubernetes, no vendor lock-in, just Docker and simple configuration.

What is Haloy?

Haloy is an open-source, MIT-licensed deployment tool that makes it simple to deploy Docker-based applications to your own servers. It handles SSL certificates, routing, and container orchestration without the complexity of Kubernetes or cloud platforms.

Complete source code: github.com/haloydev/examples/tanstack-start-postgres

What We're Building

A full-stack todo application using:

TanStack Start - React meta-framework with server functions
PostgreSQL - Production database
Drizzle ORM - Type-safe database queries
Haloy - Simple deployment to your own server

Prerequisites

Before starting, you'll need:

Node.js 20+
A Linux server (VPS or dedicated)
A domain or subdomain
Basic React and TypeScript knowledge

This guide uses pnpm, but npm works too. Just replace pnpm add with npm install and pnpm with npm run.

Project Setup

Initialize the Project

mkdir my-tanstack-app
cd my-tanstack-app
pnpm init

Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

Install Dependencies

# TanStack Start and React
pnpm add @tanstack/react-start @tanstack/react-router react react-dom nitro

# Dev dependencies
pnpm add -D vite @vitejs/plugin-react typescript @types/react @types/react-dom @types/node vite-tsconfig-paths

# Database
pnpm add drizzle-orm pg dotenv
pnpm add -D drizzle-kit @types/pg

Update package.json

Add these fields to your package.json:

{
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node .output/server/index.mjs",
    "db:push": "drizzle-kit push",
    "db:studio": "drizzle-kit studio"
  }
}

Important: The "type": "module" field is crucial. Without it, Node.js treats files as CommonJS, causing errors. TanStack Start requires ES modules.

Create Vite Configuration

Create vite.config.ts:

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";
import tsConfigPaths from "vite-tsconfig-paths";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tsConfigPaths(),
    tanstackStart(),
    nitro(),
    viteReact(), // Must come after tanstackStart
  ],
  nitro: {},
});

TanStack Start uses Nitro as its server engine. The default Node.js preset works perfectly with Haloy - no extra configuration needed.

Database Setup

Configure Drizzle

Create drizzle.config.ts:

import { config } from "dotenv";
import { defineConfig } from "drizzle-kit";
import { getDatabaseUrl } from "./src/db/database-url";

config();

const databaseUrl = getDatabaseUrl();

export default defineConfig({
  out: "./drizzle",
  schema: "./src/db/schema.ts",
  dialect: "postgresql",
  dbCredentials: {
    url: databaseUrl,
  },
});

Create Database Client

Create src/db/index.ts:

import "dotenv/config";
import { drizzle } from "drizzle-orm/node-postgres";
import { getDatabaseUrl } from "./database-url";

const databaseUrl = getDatabaseUrl();

const db = drizzle(databaseUrl);
export { db };

Define Schema

Create src/db/schema.ts:

import { integer, pgTable, timestamp, varchar } from "drizzle-orm/pg-core";

export const todos = pgTable("todos", {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  title: varchar({ length: 255 }).notNull(),
  createdAt: timestamp({ mode: "date" }).defaultNow(),
});

Database Connection Helper

Create src/db/database-url.ts:

export function getDatabaseUrl() {
  const postgresUser = process.env.POSTGRES_USER;
  if (!postgresUser) {
    throw new Error("POSTGRES_USER environment variable not found");
  }

  const postgresPassword = process.env.POSTGRES_PASSWORD;
  if (!postgresPassword) {
    throw new Error("POSTGRES_PASSWORD environment variable not found");
  }

  const postgresDb = process.env.POSTGRES_DB;
  if (!postgresDb) {
    throw new Error("POSTGRES_DB environment variable not found");
  }

  // Use 'postgres' hostname in production, localhost in development
  const host = process.env.NODE_ENV === "production" ? "postgres" : "localhost";

  return `postgres://${postgresUser}:${postgresPassword}@${host}:5432/${postgresDb}`;
}

This helper automatically switches between localhost (development) and postgres (production hostname) based on NODE_ENV.

Environment Variables

Create .env for local development:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=todo_app

Local Database (Optional)

Run PostgreSQL locally using Docker:

docker run --name postgres-dev \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=todo_app \
  -p 5432:5432 \
  -d postgres:18

To stop later:

docker stop postgres-dev
docker rm postgres-dev

Application Code

Create Router

Create src/router.tsx:

import { createRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
    defaultNotFoundComponent: () => <div>404 - not found</div>,
  });

  return router;
}

Note: The ./routeTree.gen import will show a TypeScript error until you run the dev server. TanStack Start generates this file automatically.

Root Route

Create src/routes/__root.tsx:

/// <reference types="vite/client" />

import {
  createRootRoute,
  HeadContent,
  Outlet,
  Scripts,
} from "@tanstack/react-router";
import type { ReactNode } from "react";

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

Index Route with Server Functions

Create src/routes/index.tsx:

import { createFileRoute, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { eq } from "drizzle-orm";
import { db } from "../db";
import { todos } from "../db/schema";

const getTodos = createServerFn({
  method: "GET",
}).handler(async () => await db.select().from(todos));

const addTodo = createServerFn({ method: "POST" })
  .inputValidator((data: FormData) => {
    if (!(data instanceof FormData)) {
      throw new Error("Expected FormData");
    }
    return {
      title: data.get("title")?.toString() || "",
    };
  })
  .handler(async ({ data }) => {
    await db.insert(todos).values({ title: data.title });
  });

const deleteTodo = createServerFn({ method: "POST" })
  .inputValidator((data: number) => data)
  .handler(async ({ data }) => {
    await db.delete(todos).where(eq(todos.id, data));
  });

export const Route = createFileRoute("/")({
  component: RouteComponent,
  loader: async () => await getTodos(),
});

function RouteComponent() {
  const router = useRouter();
  const todos = Route.useLoaderData();

  return (
    <div>
      <ul>
        {todos.map((todo) => (
          <li key={todo.id}>
            {todo.title}
            <button
              type="button"
              onClick={async () => {
                await deleteTodo({ data: todo.id });
                router.invalidate();
              }}
            >
              X
            </button>
          </li>
        ))}
      </ul>
      <h2>Add todo</h2>
      <form
        onSubmit={async (e) => {
          e.preventDefault();
          const form = e.currentTarget;
          const data = new FormData(form);
          await addTodo({ data });
          router.invalidate();
          form.reset();
        }}
      >
        <input name="title" placeholder="Enter a new todo..." />
        <button type="submit">Add</button>
      </form>
    </div>
  );
}

Health Check Route

Create src/routes/health.tsx:

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/health")({
  server: {
    handlers: {
      GET: async () => {
        return Response.json({ status: "ok" });
      },
    },
  },
});

This endpoint responds without querying the database, ensuring fast health checks.

Docker Configuration

Dockerfile

Create Dockerfile:

FROM node:24-slim AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
COPY . /app
WORKDIR /app

FROM base AS prod-deps
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile

FROM base AS build
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
RUN pnpm run build

FROM base
COPY --from=prod-deps /app/node_modules /app/node_modules
COPY --from=build /app/.output /app/.output

HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \
CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"

CMD ["pnpm", "start"]

Key features:

Multi-stage builds for smaller images
Built-in health check using the /health endpoint
Production-optimized dependencies

.dockerignore

Create .dockerignore:

node_modules
.git
.gitignore
*.md
dist
.DS_Store

Haloy Configuration

Create haloy.yml:

# Global configuration
server: your-server.haloy.dev
env:
  - name: POSTGRES_USER
    value: postgres
  - name: POSTGRES_PASSWORD
    value: "postgres"
  - name: POSTGRES_DB
    value: "todo_app"

targets:
  # Database Service
  postgres:
    preset: database
    image:
      repository: postgres:18
    port: 5432
    volumes:
      - postgres-data:/var/lib/postgresql

  # Application Service
  tanstack-start-postgres:
    domains:
      - domain: my-app.example.com
    port: 3000
    env:
      - name: NODE_ENV
        value: production

Replace these values:

your-server.haloy.dev - Your actual server domain
my-app.example.com - Your application domain
POSTGRES_PASSWORD - A strong password for production

Configuration Explained

We define two targets:

postgres:
- Official PostgreSQL 18 image
- Persistent storage with named volume
- Accessible to other containers via hostname postgres
tanstack-start-postgres:
- Your application code
- Connects to database using environment variables
- NODE_ENV=production ensures correct database hostname

The named volume ensures data persists across deployments and restarts.

Deployment

Install Haloy

First, install Haloy on your local machine and set up your server:

# Install Haloy CLI
curl -fsSL https://haloy.dev/install.sh | sh

# Set up your server
haloy server setup

Follow the prompts to configure your server. See the Haloy quickstart for detailed instructions.

Test Locally

Before deploying, verify everything works:

# Push schema to local database
pnpm db:push

# Start development server
pnpm dev

Visit http://localhost:3000 and test the todo functionality.

Deploy Database

Deploy PostgreSQL first:

haloy deploy -t postgres

Wait for the deployment to complete.

Note: If you're running a local PostgreSQL container for testing, stop it first:

docker stop postgres-dev

Push Schema to Production

Use Haloy's tunnel feature to connect to the production database:

# Terminal 1: Open tunnel
haloy tunnel 5432 -t postgres

In another terminal, push your schema:

# Terminal 2: Push schema
pnpm db:push

Drizzle connects to localhost:5432 (which tunnels to production) and applies your schema.

Deploy Application

Now deploy your application:

haloy deploy -t tanstack-start-postgres

Verify Deployment

# Check status
haloy status --all

# View logs
haloy logs -t tanstack-start-postgres

Your application is now live with automatic HTTPS!

Working with Production Database

The tunnel feature is useful for ongoing database management.

Inspect Data with Drizzle Studio

# Terminal 1: Open tunnel
haloy tunnel 5432 -t postgres

# Terminal 2: Start Drizzle Studio
pnpm db:studio

Open https://local.drizzle.studio to browse your production data visually.

Update Schema

When you modify src/db/schema.ts, push changes to production:

# Terminal 1: Open tunnel (if not already open)
haloy tunnel 5432 -t postgres

# Terminal 2: Push changes
pnpm db:push

Drizzle shows a diff and prompts for confirmation before applying changes.

Alternative: Migration-Based Workflow

The drizzle-kit push approach is ideal for solo developers who want to move fast. For teams or projects requiring controlled change management, consider using Drizzle Migrations.

Migrations capture schema changes as versioned SQL files that can be reviewed in pull requests and applied consistently across environments.

Why Haloy?

Haloy is designed for developers who want:

✅ Simple deployments without Kubernetes complexity
✅ Self-hosted, Docker-based infrastructure
✅ Clean dev/staging/production separation
✅ Fast "build → ship → run" workflow
✅ Zero vendor lock-in

It's perfect for:

Indie developers
Small teams
Self-hosted SaaS
API services
Internal tools

Next Steps

Questions or feedback? Drop a comment below or open an issue on GitHub!

Deploy TanStack Start with SQLite to Your Own Server

Andreas M — Sun, 14 Dec 2025 21:33:18 +0000

This guide walks you through deploying a TanStack Start application with SQLite database to your own server. Any Linux-based VPS or dedicated server will work.

We'll use Haloy for deployment. A open source tool that deploys and orchestrates Docker containers on your own servers with automatic HTTPS.

The complete source code is available at github.com/haloydev/examples/tanstack-start-sqlite.

Why This Stack?

There is no such thing as the perfect stack, but one combination I'm super excited about right now is TanStack Start and SQLite. Here's why:

Simplicity is King. You are building an app, not managing a database cluster. SQLite runs in the same process as your app. There’s no network latency between your web server and your database. Development setup is non-existent. Run pnpm install and start coding. It’s glorious.
Performance out of the box. Because the database lives right next to your server code, reads and writes are incredibly fast. You get local-file-system speeds which often blow network-attached database servers out of the water for typical web requests.
Deployment is easy. You deploy your app server and the database file (mounted as a persistent volume) to a single region with Haloy

What You'll Build

A full-stack React application using:

TanStack Start - React meta-framework with file-based routing and server functions
SQLite - Lightweight, file-based database
Drizzle ORM - TypeScript ORM for type-safe database queries
Haloy - Simple deployment to your own server

Prerequisites

Node.js 20+ installed
Haloy installed (Quickstart)
A linux server (VPS or dedicated server)
A domain or a subdomain
Basic familiarity with React and TypeScript

Project Setup

1. Initialize the Project

mkdir my-tanstack-app
cd my-tanstack-app
pnpm init

2. Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true
  }
}

3. Install Dependencies

Install TanStack Start and React:

pnpm add @tanstack/react-start @tanstack/react-router react react-dom nitro

Install dev dependencies:

pnpm add -D vite @vitejs/plugin-react typescript @types/react @types/react-dom @types/node vite-tsconfig-paths

Install Drizzle and SQLite:

pnpm add drizzle-orm @libsql/client dotenv drizzle-kit

Note: drizzle-kit is installed as a production dependency (not -D) because we need it available in the Docker container to run migrations at startup.

4. Update package.json

Update your package.json with the required configuration and scripts:

{
  // ...
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node .output/server/index.mjs",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate"
  }
}

5. Create Vite Configuration

Create vite.config.ts:

import { defineConfig } from "vite";
import { nitro } from "nitro/vite";
import tsConfigPaths from "vite-tsconfig-paths";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tsConfigPaths(),
    tanstackStart(),
    nitro(),
    // react's vite plugin must come after start's vite plugin
    viteReact(),
  ],
  nitro: {},
});

About Nitro

TanStack Start uses Nitro as its server engine. For this deployment, we're using the default Node.js preset, which works perfectly with Haloy. No additional configuration is needed. The empty nitro: {} object is sufficient.

Database Setup

1. Configure Drizzle

Create drizzle.config.ts:

import { config } from "dotenv";
import { defineConfig } from "drizzle-kit";

config();

const databaseUrl = process.env.DATABASE_URL;
if (!databaseUrl) {
  throw new Error("DATABASE_URL is not set");
}

export default defineConfig({
  out: "./drizzle",
  schema: "./src/db/schema.ts",
  dialect: "sqlite",
  dbCredentials: {
    url: databaseUrl,
  },
});

2. Create Database Client

Create src/db/index.ts:

import "dotenv/config";
import { createClient } from "@libsql/client";
import { drizzle } from "drizzle-orm/libsql";

const databaseUrl = process.env.DATABASE_URL;
if (!databaseUrl) {
  throw new Error("DATABASE_URL is not set");
}

const client = createClient({ url: databaseUrl });
const db = drizzle({ client });
export { client, db };

3. Define Your Schema

Create src/db/schema.ts:

import { sql } from "drizzle-orm";
import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const todos = sqliteTable("todos", {
  id: integer("id", { mode: "number" }).primaryKey({
    autoIncrement: true,
  }),
  title: text("title").notNull(),
  createdAt: integer("created_at", { mode: "timestamp" }).default(
    sql`(unixepoch())`
  ),
});

4. Create Environment File

Create .env for local development:

DATABASE_URL=file:local.db

5. Generate and Run Migrations

pnpm db:generate
pnpm db:migrate

This creates migration files in the drizzle/ directory that will be used in production.

Application Code

1. Create the Router

Create src/router.tsx:

import { createRouter } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

export function getRouter() {
  const router = createRouter({
    routeTree,
    scrollRestoration: true,
    defaultNotFoundComponent: () => <div>404 - not found</div>,
  });

  return router;
}

Note: You might see a TypeScript error about ./routeTree.gen not being found. This is expected. TanStack Start automatically generates this file when you run the dev server in the next steps.

2. Create the Root Route

Create src/routes/__root.tsx:

/// <reference types="vite/client" />

import {
  createRootRoute,
  HeadContent,
  Outlet,
  Scripts,
} from "@tanstack/react-router";
import type { ReactNode } from "react";

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

3. Create the Index Route

Create src/routes/index.tsx:

import { createFileRoute, useRouter } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { eq } from "drizzle-orm";
import { db } from "../db";
import { todos } from "../db/schema";

const getTodos = createServerFn({
  method: "GET",
}).handler(async () => await db.select().from(todos));

const addTodo = createServerFn({ method: "POST" })
  .inputValidator((data: FormData) => {
    if (!(data instanceof FormData)) {
      throw new Error("Expected FormData");
    }
    return {
      title: data.get("title")?.toString() || "",
    };
  })
  .handler(async ({ data }) => {
    await db.insert(todos).values({ title: data.title });
  });

const deleteTodo = createServerFn({ method: "POST" })
  .inputValidator((data: number) => data)
  .handler(async ({ data }) => {
    await db.delete(todos).where(eq(todos.id, data));
  });

export const Route = createFileRoute("/")({
  component: RouteComponent,
  loader: async () => await getTodos(),
});

function RouteComponent() {
  const router = useRouter();
  const todos = Route.useLoaderData();

  return (
    <div>
      <ul>
        {todos.map((todo) => (
          <li key={todo.id}>
            {todo.title}
            <button
              type="button"
              onClick={async () => {
                  await deleteTodo({ data: todo.id });
                  router.invalidate();
                }}
              >
                X
              </button>
            </li>
          ))}
        </ul>
        <h2>Add todo</h2>
        <form
          onSubmit={async (e) => {
            e.preventDefault();
            const form = e.currentTarget;
            const data = new FormData(form);
            await addTodo({ data });
            router.invalidate();
            form.reset();
          }}
        >
          <input name="title" placeholder="Enter a new todo..." />
          <button type="submit">Add</button>
        </form>
      </div>
    );
  }

Docker Configuration

1. Create Dockerfile

Create Dockerfile:

FROM node:24-slim AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
COPY . /app
WORKDIR /app

FROM base AS prod-deps
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --prod --frozen-lockfile

FROM base AS build
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
RUN pnpm run build

FROM base
COPY --from=prod-deps /app/node_modules /app/node_modules
COPY --from=build /app/.output /app/.output
CMD [ "sh", "-c", "pnpm db:migrate && pnpm start" ]

Key points:

Uses multi-stage builds for smaller final image
Runs database migrations at container startup. This is safe because Drizzle migrations are idempotent (running them multiple times has no effect if the database is already up to date)
Production dependencies include drizzle-kit for migrations

2. Create .dockerignore

Create .dockerignore:

We need to exclude files from the built Docker image. Notice *.db is excluded. Your local database should never be copied to production. The production database lives in the persistent volume.

node_modules
.git
.gitignore
*.md
dist
.DS_Store
*.db

Haloy Configuration

Create haloy.yml:

This file tells the haloy CLI tool how to deploy your app. It's pretty simple and straightforward.

name: my-tanstack-app
server: your-server.haloy.dev
domains:
  - domain: my-app.example.com
port: 3000
env:
  - name: NODE_ENV
    value: production
  - name: DATABASE_URL
    value: "file:/app/db-data/production.db"
volumes:
  - "db-data:/app/db-data"

Configuration Explained

Field	Description
`name`	Unique identifier for your application
`server`	Your Haloy server domain
`domains`	Public domain(s) for your app (HTTPS is automatic)
`port`	The port your app listens on inside the container. Nitro defaults to port 3000, which matches the Vite config
`env`	Environment variables passed to your container
`volumes`	Persistent storage - critical for SQLite data

Volume Configuration

The volumes configuration is critical for SQLite. See Volumes for more details on persistent storage.

volumes:
  - "db-data:/app/db-data"

This creates a named volume db-data mounted at /app/db-data inside the container. The DATABASE_URL points to a file in this directory, ensuring your database persists across deployments and container restarts.

Deploy

1. Test Locally

Before deploying, verify everything works locally. If you haven't already, make sure you've completed the database setup steps above (create .env, generate and run migrations).

pnpm dev

Visit http://localhost:3000 and try adding a todo to verify both the app and database are working correctly.

2. Deploy with Haloy

If everything is working locally, you can now deploy to your server. Make sure you have Haloy installed and have configured your domain's DNS to point to your server. Check out the Quickstart if you haven't set it up yet.

haloy deploy

Haloy will:

Build your Docker image locally
Push it to your server
Run the container with your configuration
Set up HTTPS automatically
Route traffic to your app

3. Verify Deployment

# Check status
haloy status

# View logs
haloy logs

Your app should now be live.

Production Considerations

Database Backups

SQLite stores all data in a single file. To back up your database:

# Execute a backup command in the container
haloy exec -- cp /app/db-data/production.db /app/db-data/backup-$(date +%Y%m%d).db

Consider setting up automated backups using a cron job or scheduled task.

Monitoring

View your application logs:

# Stream logs
haloy logs

# Check application status
haloy status

Troubleshooting

Database Not Persisting

Ensure your volumes configuration matches your DATABASE_URL:

env:
  - name: DATABASE_URL
    value: "file:/app/db-data/production.db"  # Must be inside the volume mount
volumes:
  - "db-data:/app/db-data"  # Volume mounted here

You can use haloy exec to run commands inside your container for debugging. Verify the database file exists and is being written to the correct location:

haloy exec -- ls -la /app/db-data/

Migration Errors

If migrations fail at startup, check:

The drizzle/ directory is included in your Docker image
drizzle-kit is a production dependency (not devDependency)
Logs for specific error messages: haloy logs

Verify the migration files are present in the container:

haloy exec -- ls -la /app/drizzle/

Connection Issues

If you can't connect to your deployed app:

Verify the domain is correctly configured: haloy status
Check the app is running: haloy logs
Ensure port 3000 matches your app's listening port

Scaling Limitations

SQLite is designed for single-server deployments. If you need to run multiple replicas of your application, you have two options:

Switch to a client-server database like PostgreSQL or MySQL
Use a distributed SQLite solution like Turso or LiteFS

For most applications, a single replica with SQLite can handle significant traffic. Often more than you'd expect.