Notploy

Notploy Instance

Fix a Notploy UI that isn't accessible and recreate the core Notploy services.

My Notploy UI Instance is Not Accessible

If you can't access your Notploy UI instance, there could be several causes. While this issue won't occur with Notploy Cloud (where our team manages the infrastructure), self-hosted instances might encounter configuration problems.

Let's go through the possible cases where your Notploy UI instance might be inaccessible:

1. Insufficient Storage Space

If you've made many deployments and don't have available space on your server, the Notploy database might enter recovery mode, preventing access to the user interface. Here's a quick solution to clear cache and free up server space:

docker system prune -a
docker builder prune -a
docker image prune -a

2. Container Race Condition During Restart

During a restart, a race condition might occur where Notploy's dependent containers don't start in the correct order. To troubleshoot this:

First, verify the running containers:

docker ps

You should see all three of these containers running:

2a5b955c32b6  ghcr.io/skygenesisenterprise/notploy:latest      "docker-entrypoint.s…"   4 days ago     Up 4 days     0.0.0.0:3000->3000/tcp, :::3000->3000/tcp                                                                             notploy.1.4bkuszk98muz372kw5mvwkw0h
5a989bf52bc6   postgres:16                 "docker-entrypoint.s…"   4 days ago     Up 4 days     5432/tcp                                                                                                              notploy-postgres.1.9hvjaxrmby7ex2denjtwo0csf
05be01c5612f   traefik:v2.5                "/entrypoint.sh trae…"   4 days ago     Up 4 days     0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp   notploy-traefik.1.2oktabjmfu558x2d2dy6czt8m

Note: If you're running a version older than v0.29.9, you'll also see a notploy-redis container. Redis is no longer used in self-hosted Notploy since v0.29.9.

If all three containers are running but you still can't access the interface, it's time to debug:

Debugging Process

1. Check Container Logs

Start by examining the logs of each container:

docker service logs notploy # Notploy UI
docker service logs notploy-postgres # Postgres
docker logs notploy-traefik # Traefik

2. Common Database Connection Issue

A common case is when the Postgres container starts after the Notploy container, preventing Notploy from connecting to the database. You might see logs like this when running docker service logs notploy:

> notploy@v0.22.3 start /app
> node -r dotenv/config dist/server.mjs

Default middlewares already exists
Network is already initilized
Main config already exists
Default traefik config already exists
Migration failed [Error: getaddrinfo ENOTFOUND notploy-postgres] {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'notploy-postgres'
}
Setting up cron jobs....
Main Server Error [Error: getaddrinfo ENOTFOUND notploy-postgres] {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'notploy-postgres'
}

To fix this, restart the Notploy service:

docker service scale notploy=0
# Then
docker service scale notploy=1

3. Traefik Configuration Issues

If all containers are running but you still can't access the UI, and Notploy logs show no errors, the Traefik container might have configuration issues.

When running docker logs notploy-traefik, you might see errors like:

2025-04-07T15:20:18Z ERR Error occurred during watcher callback error="/etc/notploy/traefik/dynamic/notploy.yml: field not found, node: passHostHeader" providerName=file

First, try restarting Traefik:

docker restart notploy-traefik

If you still can't access it and the same error persists in the Traefik logs, you'll need to check the Traefik configuration. In this case, the error indicates that the passHostHeader field is missing in the configuration.

If you've modified any Traefik configuration for an application and added invalid configuration, the logs will point to the error. For example, the error above mentions field not found, node: passHostHeader, which means we need to manually modify the configuration files in /etc/notploy/traefik.

Here's an example of an invalid configuration:

http:
  routers:
    notploy-router-app:
      rule: Host(`my-domain.com`)
      service: notploy-service-app
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
    notploy-router-app-secure:
      rule: Host(`my-domain.com`)
      service: notploy-service-app
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
  services:
    notploy-service-app:
      loadBalancer:
        servers:
          - url: http://notploy:3000
          - passHostHeader: true

The correct configuration should be:

http:
  routers:
    notploy-router-app:
      rule: Host(`my-domain.com`)
      service: notploy-service-app
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
    notploy-router-app-secure:
      rule: Host(`my-domain.com`)
      service: notploy-service-app
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
  services:
    notploy-service-app:
      loadBalancer:
        servers:
          - url: http://notploy:3000
        passHostHeader: true

After fixing the configuration, restart Traefik:

docker restart notploy-traefik

You should now be able to access the user interface.

Recreate notploy containers

In the case you want to recreate the notploy services, you can do the following:

Important: Before recreating services, make sure you have backups of your data. Recreating services will not delete your volumes, but it's always good to have backups.

Recreate Postgres Service

Remove and recreate the notploy-postgres service:

docker service rm notploy-postgres

# Create a new notploy-postgres service with Docker Secrets
docker service create \
  --name notploy-postgres \
  --constraint 'node.role==manager' \
  --network notploy-network \
  --env POSTGRES_USER=notploy \
  --env POSTGRES_DB=notploy \
  --secret source=notploy_postgres_password,target=/run/secrets/postgres_password \
  --env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  --mount type=volume,source=notploy-postgres,target=/var/lib/postgresql/data \
  postgres:16

Note: Using Docker Secrets is the recommended approach for managing sensitive data like passwords. The secret is encrypted and only available to services that have been granted access to it.

Recreate Traefik Service

Remove the notploy-traefik service:

# If you are using docker standalone traefik
docker rm -f notploy-traefik

docker run -d \
    --name notploy-traefik \
    --restart always \
    -v /etc/notploy/traefik/traefik.yml:/etc/traefik/traefik.yml \
    -v /etc/notploy/traefik/dynamic:/etc/notploy/traefik/dynamic \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -p 80:80/tcp \
    -p 443:443/tcp \
    -p 443:443/udp \
    traefik:v3.6.25

docker network connect notploy-network notploy-traefik

# If you are using docker service traefik
docker service rm notploy-traefik

# Create a new notploy-traefik service
docker service create \
  --name notploy-traefik \
  --constraint 'node.role==manager' \
  --network notploy-network \
  --mount type=bind,source=/etc/notploy/traefik/traefik.yml,target=/etc/traefik/traefik.yml \
  --mount type=bind,source=/etc/notploy/traefik/dynamic,target=/etc/notploy/traefik/dynamic \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --publish mode=host,published=443,target=443 \
  --publish mode=host,published=80,target=80 \
  --publish mode=host,published=443,target=443,protocol=udp \
  traefik:v3.6.25

Recreate Notploy Service

Remove and recreate the notploy service:

If the notploy_auth_secret secret doesn't exist on your server (installations older than v0.29.3), create it first: openssl rand -hex 32 | docker secret create notploy_auth_secret -

docker service rm notploy

# Create the notploy service
docker service create \
  --name notploy \
  --replicas 1 \
  --network notploy-network \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --mount type=bind,source=/etc/notploy,target=/etc/notploy \
  --mount type=volume,source=notploy,target=/root/.docker \
  --secret source=notploy_postgres_password,target=/run/secrets/postgres_password \
  --secret source=notploy_auth_secret,target=/run/secrets/notploy_auth_secret \
  --publish published=3000,target=3000,mode=host \
  --update-parallelism 1 \
  --update-order stop-first \
  --constraint 'node.role == manager' \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -e BETTER_AUTH_SECRET_FILE=/run/secrets/notploy_auth_secret \
 ghcr.io/skygenesisenterprise/notploy:latest

For Proxmox LXC environments, add the --endpoint-mode dnsrr flag to all services:

docker service create \
  --name notploy \
  --replicas 1 \
  --network notploy-network \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --mount type=bind,source=/etc/notploy,target=/etc/notploy \
  --mount type=volume,source=notploy,target=/root/.docker \
  --secret source=notploy_postgres_password,target=/run/secrets/postgres_password \
  --secret source=notploy_auth_secret,target=/run/secrets/notploy_auth_secret \
  --publish published=3000,target=3000,mode=host \
  --update-parallelism 1 \
  --update-order stop-first \
  --constraint 'node.role == manager' \
  --endpoint-mode dnsrr \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -e BETTER_AUTH_SECRET_FILE=/run/secrets/notploy_auth_secret \
 ghcr.io/skygenesisenterprise/notploy:latest

Final Notes

While the specific issues may vary, the general troubleshooting approach remains similar to what we've described above, and is the general way we always follow when correcting a problem related to the notploy instance not starting.. If you still can't access the user interface:

  1. Check that all containers are running properly
  2. Review the logs of each container for specific error messages
  3. Verify all configuration files
  4. Make sure to read the Traefik documentation for detailed configuration options: https://doc.traefik.io/traefik/

Notploy Cloud

If you are using Notploy Cloud, you don't need to worry about this, our team will handle the infrastructure for you.

Start using Notploy Cloud https://app.notploy.com/

Logs & Monitoring

Fix logs and monitoring that aren't loading on worker nodes or remote servers.

SDK

Use the TypeScript SDK to drive Notploy programmatically.

On this page

My Notploy UI Instance is Not Accessible1. Insufficient Storage Space2. Container Race Condition During RestartDebugging Process1. Check Container Logs2. Common Database Connection Issue3. Traefik Configuration IssuesRecreate notploy containersRecreate Postgres ServiceRecreate Traefik ServiceRecreate Notploy ServiceFinal Notes