DEV Community: Jookllo

The Issues of Deploying Laravel on Dokploy: Database Connection Hell

Jookllo — Mon, 03 Aug 2026 07:38:08 +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.

Mastering Self-Hosted Convex: A Complete Deployment Guide

Jookllo — Wed, 10 Jun 2026 23:44:00 +0000

Mastering Self-Hosted Convex: A Complete Deployment Guide

So, you've decided to take control of your data and self-host Convex. 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

4. The Big Moment: Deploying

Now, let's push your code. We're going to use the official {% raw %}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.

How to Structure your Resume After your First Job

Jookllo — Sat, 04 Nov 2023 08:49:46 +0000

After about one or two years experience in software development, how did you strucutre your resume? Like did it still have personal projects and work experience or did you just focus on adding the projects that you have done for your organization because I am genuinely stuck about this. Advice would be appreciated.😁

A Beginner trying to understand and use node by doing a project

Jookllo — Wed, 02 Oct 2019 11:00:30 +0000

Hello,

This is probably super random for me but I decided to create a simple node js project. My classmate had seen me using php ,he doesn't hold php in high regard, recommended that I use node. He believed that javascript isn't going anywhere and recommended nodejs.

The Hand Dealing

I decided that since I had seen node around various blogs and videos whats the harm in actually trying. So, after a few installations and plugins for vs code later, I have node set up and will create a simple news applicaiton for financial news (not something big but still...). This will allow things like requesting apis for the news and maybe a few stock tips. An update will be done hopefully every week and I hope to receive helpful feedback and criticism.
The repo will be added later for those interested.
Have a good day :)

Is it lazy for someone to make a site from a template?

Jookllo — Sat, 15 Jun 2019 05:26:30 +0000

Hello
A beginner here. When making a site do you make it from pure nothingness or use the already existing sources online to make one. Is it also lazy for someone to make a site using a template? I get a feeling that it doesn't come out as original to use an online template.

DEV Community: Jookllo

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

Mastering Self-Hosted Convex: A Complete Deployment Guide

Mastering Self-Hosted Convex: 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

How to Structure your Resume After your First Job

A Beginner trying to understand and use node by doing a project

Hello,

The Hand Dealing

Is it lazy for someone to make a site from a template?

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

Missing `_generated` files in your frontend