Coder Legion - Recent posts tagged dokploy

Mastering Self-Hosted Convex on Dokploy: A Complete Deployment Guide

Mon, 03 Aug 2026 07:41:58 +0000

So, you've decided to take control of your data and self-host Convex. It's a great choice but if you've tried pushing your functions to a local or private server, you might have run into cryptic errors about "Relative import paths" or "Missing modules."

The secret? You don't need custom deployment scripts. In fact, you shouldn't use them. The official Convex CLI is actually powerful enough to handle self-hosted deployments perfectly—if you know which buttons to press.

In this guide, I’ll show you exactly how to configure your project and deploy your functions like a pro.

1. Before You Start

Before we dive into the code, make sure you have the following ready:

Your Convex Instance: Whether you're using Dokploy, Docker, or a raw VPS, your backend should be up and running.
The Admin Key: You'll need the master key for your server.
- Tip: If you're using Dokploy, you can usually generate this by running ./generate_admin_key.sh inside your backend container's terminal.
The CLI: Make sure you have the latest version of Convex installed locally:
```
npm install convex
```

2. Preparing Your Project

For a smooth deployment, your convex/ folder needs to be a bit more "independent."

Step 1: Give Convex its own Identity

Create a package.json inside your convex/ directory. This ensures the CLI knows exactly which dependencies to bundle when it prepares your code for the server.

{
  "name": "my-convex-backend",
  "private": true,
  "type": "module",
  "dependencies": {
    "convex": "^1.16.0",
    "typescript": "^5.0.0"
  }
}

Step 2: Fix your Config

Ensure your convex/convex.config.ts is using the modern defineApp export. The server expects this structure to understand your app's layout.

import { defineApp } from "convex/server";

export default defineApp();

3. The Magic Environment Variables

The Convex CLI is "Cloud-first" by default, but we can tell it to target our own server by setting two specific environment variables.

Variable	What it does
`CONVEX_SELF_HOSTED_URL`	Points the CLI to your backend URL (e.g., `https://api.myapp.com`).
`CONVEX_SELF_HOSTED_ADMIN_KEY`	Your secret key. Crucial: It must include the `convex-self-hosted\|` prefix!

4. The Big Moment: Deploying

Now, let's push your code. We're going to use the official deploy command.

Run this from your root or convex directory:

CONVEX_SELF_HOSTED_URL="https://your-api-url.com" \
CONVEX_SELF_HOSTED_ADMIN_KEY="convex-self-hosted|your-key-here" \
npx convex deploy --typecheck disable

Why this works where other scripts fail:

When you use a custom fetch script to send files, you're just sending raw text. The server has no idea where convex/server is.

The CLI is smarter. It uses esbuild to "bundle" your code into a single, self-contained JavaScript package. It finds all your imports and bakes them right into the file so the server can run them instantly.

5. Pro Tip: Automate Everything

Don't type those long variables every time. Add a script to your convex/package.json:

"scripts": {
  "deploy": "CONVEX_SELF_HOSTED_URL=... CONVEX_SELF_HOSTED_ADMIN_KEY=... npx convex deploy --typecheck disable"
}

Now, all it takes is a simple:

npm run deploy

Troubleshooting common "Gotchas"

"Relative import path 'convex/server' not found"

If you see this, you likely bypassed the CLI. Always use npx convex deploy so the bundler can do its job!

"BadAdminKey"

Double-check your key. Most people forget the convex-self-hosted| prefix. Without it, the server will reject your request every time.

Missing `_generated` files in your frontend

Run npx convex codegen while your CONVEX_SELF_HOSTED_URL is set to update your local TypeScript types to match what you just deployed.

Happy hosting! Your Convex backend is now truly yours.

The Issues of Deploying Laravel on Dokploy: Database Connection Hell

Mon, 03 Aug 2026 07:41:12 +0000

If you’ve tried deploying a Laravel application on Dokploy (the self-hosted Heroku alternative built on Docker) and immediately ran into a wall of Database connection refused or SQLSTATE[HY000] [2002] errors, you are not alone.

It works perfectly on your local machine, but the moment it hits the server, it falls apart. Here is a real-world breakdown of the database connectivity issues we experienced, why they happened, and how to fix them.

1. The "Localhost" Trap (The `127.0.0.1` Connection Refused)

The Issue

On your local computer, you probably set your .env to:

DB_HOST=127.0.0.1
DB_PORT=3306

When you deploy this to Dokploy, your Laravel application crashes on start because it cannot connect to the database.

The Reason

Dokploy runs everything in isolated Docker Containers.
Inside a container, 127.0.0.1 or localhost refers to the Laravel container itself, not the host machine or your database container. Since there is no database running inside your Laravel code container, it refuses the connection.

The Solution

You must use Docker's internal networking.

If your database is created inside Dokploy, Dokploy assigns it a specific network service name (e.g. dokploy-db-mysql or the service name you typed in the database creation wizard).
Change your host in the Dokploy Environment Variables UI to match that service name:
```
DB_HOST=dokploy-db-mysql  # Use Dokploy's internal container name
```

2. The Config Caching Nightmare (Why changing Env Variables in the UI did nothing)

The Issue

You realized the host was wrong, went to the Dokploy dashboard, updated the DB_HOST environment variable to the correct container hostname, saved, and redeployed.
Yet, the app still threw the old connection error looking for 127.0.0.1. You checked the container logs, confirmed the new environment variables were set, but Laravel simply ignored them.

The Reason

This happens if you run configuration caching in your Dockerfile during the build step:

RUN php artisan config:cache

When Laravel builds your container, it runs config:cache and bakes whatever .env values exist at build-time directly into a static cache file (bootstrap/cache/config.php).
At runtime, Laravel completely ignores your Dokploy UI environment variables and loads the baked-in values instead.

The Solution

Never cache your configuration during the Docker build stage if you plan to change environment variables dynamically.

Remove RUN php artisan config:cache from your build steps.
If you want caching for speed in production, clear it on boot by running php artisan config:clear or php artisan optimize:clear inside your container's startup command / entrypoint script.

3. The Race Condition (Migrations crashing the build)

The Issue

You configured your Docker container to automatically run migrations on deployment:

php artisan migrate --force

But your deployment failed during this step because the database connection timed out or was refused, even though all credentials were 100% correct.

The Reason

When Dokploy restarts or provisions your stack, it starts both the Laravel container and the MySQL/PostgreSQL container simultaneously.
Laravel boots up in milliseconds and immediately tries to run migrations. However, MySQL is still executing its slow initial setup scripts, checking schemas, and opening sockets. The database container isn't ready to receive queries yet, so Laravel's migration command crashes, failing the entire Dokploy deployment.

The Solution

You need to make Laravel "wait" for the database to boot. Add a small bash loop to your entrypoint script (entrypoint.sh) that pings the database port before running migrations:

echo "Waiting for MySQL to boot..."
until nc -z -v -w30 $DB_HOST $DB_PORT; do
  echo "MySQL is not ready yet. Retrying in 2 seconds..."
  sleep 2
done
echo "MySQL is up! Running migrations..."
php artisan migrate --force

4. Port Mapping Confusion (Internal vs. External Ports)

The Issue

Mapping your Dokploy MySQL database port to 3306 (or 3307) externally so you could connect via TablePlus/DBeaver from your laptop, but when configuring your Laravel .env inside Dokploy, you weren't sure which port to use.

The Reason

Docker has two layers of ports:

Internal Port: The port the service listens to inside the Docker private network (always 3306 for MySQL).
External/Exposed Port: The port mapped to the public server IP so you can connect from the outside world (e.g., mapping host 3307 to container 3306).

Inside Dokploy, your Laravel app and your MySQL container share the same private network. Therefore, they communicate internally.

The Solution

For Laravel (.env on Dokploy): Always use the internal port (DB_PORT=3306).
For TablePlus/DBeaver (External laptop): Use the exposed host port (3307) and the public server IP.

Summary Checklist for Dokploy deployments

Set DB_HOST to the internal Docker container/service name, not 127.0.0.1.
Set DB_PORT to the internal port (3306 for MySQL), not the exposed host port.
Avoid running php artisan config:cache during Docker build time.
Implement a wait-for-it check in your startup script so migrations don't run before MySQL is fully booted.

Coder Legion - Recent posts tagged dokploy

Mastering Self-Hosted Convex on Dokploy: A Complete Deployment Guide

1. Before You Start

2. Preparing Your Project

Step 1: Give Convex its own Identity

Step 2: Fix your Config

3. The Magic Environment Variables

4. The Big Moment: Deploying

Why this works where other scripts fail:

5. Pro Tip: Automate Everything

Troubleshooting common "Gotchas"

"Relative import path 'convex/server' not found"

"BadAdminKey"

Missing _generated files in your frontend

The Issues of Deploying Laravel on Dokploy: Database Connection Hell

1. The "Localhost" Trap (The 127.0.0.1 Connection Refused)

The Issue

The Reason

The Solution

2. The Config Caching Nightmare (Why changing Env Variables in the UI did nothing)

The Issue

The Reason

The Solution

3. The Race Condition (Migrations crashing the build)

The Issue

The Reason

The Solution

4. Port Mapping Confusion (Internal vs. External Ports)

The Issue

The Reason

The Solution

Summary Checklist for Dokploy deployments

Missing `_generated` files in your frontend

1. The "Localhost" Trap (The `127.0.0.1` Connection Refused)