Your Docker image builds. The registry accepts it. n8n starts, prints its editor URL, and seems ready for your first workflow.
Then the deployment fails.
It is tempting to keep changing the Dockerfile. But once the image has built successfully, the next question is what happens when that image runs: can it write its data, reach its dependencies, pass its checks, and remain available?
This post explains how to host n8n on Hostless and how to investigate the gap between “built successfully” and “ready for workflows.”
The shortcut: the n8n template
Hostless has an n8n template under Services. It runs one n8n instance with persistent storage, a generated encryption key, public URL settings and health checks already in place. You still complete n8n’s account setup, connect your integrations and test your workflows.
Choose a custom Docker-based App when you want control over the image. That is where the gap between “built” and “ready” usually opens, so the rest of this post is about that path.
Your data needs somewhere permanent to live
n8n keeps its SQLite database, its encryption key material and its instance files in /home/node/.n8n. If that directory lives only in the container’s temporary filesystem, the next deployment starts with an empty instance. Your workflows are gone, and so are the credentials inside them.
Custom Apps on Hostless have a read-only root filesystem, so n8n cannot quietly write somewhere else either. Attach a volume at /home/node/.n8n and keep the App at one replica. One SQLite instance should have one writer.
If the App already exists, back up first. A new volume starts empty. It does not copy your old database for you.
If writes fail with EACCES or EROFS, check the mount and its ownership rather than running n8n as root to hide the problem.
The steps are in storage configuration and app filesystems.
The encryption key is part of your data
n8n encrypts every credential you save. If the key changes between deployments, n8n can no longer read them. Set N8N_ENCRYPTION_KEY once, store it as a secret environment variable, and back it up next to the database. Keep it out of Dockerfiles, Git, screenshots and support messages.
Test a restore before the instance carries real work.
Two ports that must agree
This is the failure that looks most like a broken build.
n8n listens on port 5678 by default. A custom App on Hostless sends traffic and health checks to port 8000. Start the n8n image without changing anything, and n8n waits on 5678 while Hostless knocks on 8000. Nothing answers. The image built, n8n printed its startup message, and the deployment still never becomes healthy.
Set N8N_PORT=8000 and N8N_LISTEN_ADDRESS=0.0.0.0. n8n has its own listener settings, so it does not pick up a generic PORT value. Do not change the container port to 443 because the public URL uses HTTPS. Hostless terminates HTTPS in front of the App.
Then tell n8n its public address with N8N_HOST, N8N_PROTOCOL=https and the editor and webhook URLs. After the deploy, open the editor and look at a webhook URL. It should show your public HTTPS hostname, not an internal address. The n8n webhook URL guide has the variable names for your version.
A health check that tells the truth
A TCP check proves that something accepts a connection. It does not prove that n8n can serve a request.
n8n gives you two endpoints. /healthz says the instance is reachable. /healthz/readiness says the database is connected and migrated. Use /healthz for the Hostless health check. That one check also decides restarts, so pointing it at the readiness endpoint would turn a short database problem into a restart loop. Check readiness on its own when you need it.
See health checks and the n8n monitoring guide.
If n8n starts and then receives SIGTERM
SIGTERM tells a process to stop. The signal alone does not tell you who sent it or why.
A rollout that replaces the old instance, a manual stop, or a failed check can all end in termination. An out-of-memory kill needs its own evidence. A SIGTERM line in the log is not that evidence.
Likewise, “editor accessible” proves only that the editor was reachable at that moment. It does not explain a later failure.
So read the story in order. Match the logs to the deployment you are diagnosing. Read from startup onward, and look for permission errors, migration failures and missing settings before the shutdown line. Then check the port, the mount and the health check against what you meant to configure.
A generic deployment error is where the investigation begins. It is not a diagnosis of a Dockerfile problem, a network failure or a platform fault.
Ready means tested
Before you trust the instance with automations your team depends on, prove the pieces work together. Run a small workflow. Call a production webhook from outside. Restart the App and check that the workflow and its credentials survive. Restore a backup once.
A reliable n8n instance needs persistent state, a consistent public address, an honest health check and enough capacity for its workflows. A green build gives you none of those on its own.
Comments