How to Self-Host NocoDB in 2026: Database Links, Auth and Persistence

There are two versions of “running NocoDB”: a container exists, or the service completes its real job. Only the second matters. Here the proof is to connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API.

NocoDB serves this purpose: spreadsheet interface over a real database. The deployment has to preserve the pieces behind that behavior; a port, a volume and a certificate are inputs, not the result.

Draw the NocoDB runtime boundary

Process health and product health are separate for NocoDB. Port 8080 may answer while the user-facing transaction still fails. The network contract for NocoDB is Postgres or MySQL for production metadata instead of a disposable local file. Keep private endpoints on internal DNS, permit only required outbound calls and give NocoDB a scoped service credential.

Use this readiness exercise after meaningful configuration changes: connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API. Keep expensive external checks out of liveness probes so a provider outage does not cause a restart loop. Capacity work should track row count, attachment traffic, metadata-database latency and simultaneous grid users, which is closer to NocoDB's real pressure than page requests.

Launch NocoDB with observable defaults

Start NocoDB in a way that leaves the route private until bootstrap is complete.

docker run -d \
  --name nocodb \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v nocodb-data:/usr/app/data \
  -e NC_AUTH_JWT_SECRET=replace-with-a-long-random-value \
  nocodb/nocodb:latest

If the process loops, compare the image's expected user with the owner of each mounted path. If it stays up, test port 8080 locally and then move directly to the workflow: connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API. Version-pin the image only after that end-to-end check passes, and record the exact configuration beside the service.

Domains, proxy headers and port 8080

Choose the final NocoDB hostname before users save callbacks or client settings, then set NC_PUBLIC_URL to the canonical HTTPS address. The platform route should terminate TLS once and target private port 8080.

Run the acceptance transaction externally. If the client never reaches NocoDB, use the SSL validation checklist for DNS and certificate checks. If the request reaches NocoDB but the metadata database is unreachable or public URLs point at an internal host, stop changing proxy redirects and inspect the application-specific boundary instead.

Design the NocoDB restore before launch

Define recovery point and recovery time for NocoDB in terms of the metadata database, attachments and any external source databases. Mount /usr/app/data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. A named volume solves redeploy persistence; it does not solve compromise or server loss.

Build a clean restore environment, use the same pinned application version and prove that bases, views, roles, attachments and source mappings return without changing rows in the connected database. Record commands, ownership fixes and elapsed time. The backup guide is a useful standard: a backup is trusted after restoration, not after upload.

Security decisions specific to NocoDB

Close the bootstrap window as soon as the first trusted administrator exists. NocoDB's concrete trap is reusing a weak JWT secret or exposing base credentials to every editor; the safer boundary is to use a stable JWT secret, limit who can create external data-source connections and review shared-view exposure.

Generate NC_AUTH_JWT_SECRET as a long random value; rotating it normally invalidates sessions or tokens, so plan the user impact rather than calling it an encryption migration. Private networking should carry dependency credentials, and roles inside NocoDB should grant the smallest useful action. Keep sensitive request bodies and provider responses out of routine logs.

Capacity and upgrade checks

A green container is necessary but not sufficient. The service-level indicator is successful completion of “connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API”, while the likely pressure signals are row count, attachment traffic, metadata-database latency and simultaneous grid users.

Change control matters because metadata migrations can affect views and automations even when the underlying source database remains untouched. Preserve the old image, test migrations on copied state and document whether rollback is supported after the schema moves. If the metadata database is unreachable or public URLs point at an internal host, diagnose the first boundary that differs from the working environment.

A production acceptance run for NocoDB

Before real users arrive, make a release worksheet for NocoDB. It must name the pinned image, port 8080, canonical origin, persistent paths and the owner of Postgres or MySQL for production metadata instead of a disposable local file. Attach the expected result of this transaction: connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API.

Use the worksheet after a normal replacement and after a clean restore. Recovery is accepted only if bases, views, roles, attachments and source mappings return without changing rows in the connected database. Also collect a short resource trace covering row count, attachment traffic, metadata-database latency and simultaneous grid users; keep it beside the release so future capacity changes are compared with the same workload.

Include one controlled failure: temporarily deny the test identity access to Postgres or MySQL for production metadata instead of a disposable local file. Confirm NocoDB reports the problem at the correct boundary, put the valid condition back and rerun the transaction. This checks error visibility, not merely success, and prevents a healthy-looking interface from concealing a broken worker, callback or database connection.

Where Dockup removes work for NocoDB

For NocoDB, Dockup is most useful at the boundary between an image and a durable service. It keeps the route to 8080, TLS, secret values and storage attached across container replacements, whether the compute belongs to Dockup or to your attached server.

Finish with application knowledge: set NC_PUBLIC_URL to the canonical HTTPS address; connect and test Postgres or MySQL for production metadata instead of a disposable local file; and run this verification: connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API. Keep the result as a deployment check so the next image update is judged by behavior rather than by container status.

Frequently asked questions

What does NocoDB need for a production deployment?

Route the NocoDB container on port 8080 through one HTTPS origin. The supporting network requirement is Postgres or MySQL for production metadata instead of a disposable local file. Do not call NocoDB ready until you can connect a disposable source database, create a grid and filtered view, edit a row, add an attachment and call the REST API.

Which NocoDB data belongs in a backup?

Persist /usr/app/data and include the metadata database, attachments and any external source databases in the same recovery manifest. A clean NocoDB restore passes only when bases, views, roles, attachments and source mappings return without changing rows in the connected database.

Does NocoDB require HTTPS behind a reverse proxy?

Use HTTPS for the public NocoDB origin and keep port 8080 on the internal route. Apply the NocoDB setting correctly: set NC_PUBLIC_URL to the canonical HTTPS address. For NocoDB, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a NocoDB upgrade be tested?

Restore current NocoDB state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because metadata migrations can affect views and automations even when the underlying source database remains untouched. Keep the previous NocoDB image until its data-migration and rollback boundary are understood.