Documentation

Docker Troubleshooting

Suggest Edits

If you run into any issues during setup, or while running Sublime, below are troubleshooting steps that can help you diagnose and fix.

Updating your Sublime host

If you installed Sublime on a remote VPS or VM, and you mistakenly used the default http://localhost Sublime host, you can follow step 3 of Manual Installation: Docker to update your sublime.env to point to the correct host. This will save you from having to reset your entire Sublime Platform.

If you want to setup a proxy such as nginx, see using a proxy.

Docker logs errors

Run the following command to look for errors:

docker compose logs | grep -i 'error\|fatal\|panic'

📘

Live tail Docker logs

You can live tail the logs at any time by running:

docker compose logs -f

Password authentication failed for user Sublime

server error (FATAL: password authentication failed for user \"sublime\")

This likely means that the sublime.env file was overwritten and the credentials are no longer valid, or you have previous installation of Sublime. If this is the case, you can either copy your old sublime.env file to your new deployment directory, or follow the steps below to wipe your Postgres volume if you don't have the old sublime.env file, and there is no data that you care to keep in Postgres.

Executable file not found in $path

exec: "docker-credential-desktop": executable file not found in $PATH

You'll need to edit ~/.docker/config.json and delete the JSON key/pair "credsStore": "desktop", (see this issue for details). You should be able to re-run your script.

No space left of device

no space left on device

See out of disk space

Docker Compose errors

Fetching server API Version

Error: `docker.errors.DockerException: Error while fetching server API version`

If you see this error when running docker compose, this likely means there's a permissions issue. You may need to run the command using sudo docker compose.

No space left on device

Error: `no space left on device`

See out of disk space

SSL errors

If you are unable to access the dashboard using https after configuring SSL, there may have been errors on startup. It can be useful to interrogate the logs from your sublime_nginx_letsencrypt container specifically to ensure no errors occurred while creating the certificate.

To do so, run: sudo docker compose logs sublime_nginx_letsencrypt

Key type of the certificate

Error: Are you trying to change the key type of the certificate...?

If you encounter this error, you most likely have already registered a certificate for your domain using a non-RSA algorithm. The easiest way to fix this is to register a new subdomain, update your configuration, and re-run installation. Since your new subdomain will not yet have been issued a certificate, installation should be able to proceed successfully.

📘

Fixing certificate collisions

  1. Register a new subdomain
  2. Update your certbot.env and sublime.env files with the new subdomain
  3. Re-run: clone_platform=false ./install-and-launch.sh

Snap is not supported

Snap installations of Docker are currently not supported because they can cause issues when using Docker Compose in the future.

If you installed Docker via Snap, you may run into problems starting the Platform. Even if you have removed the package and reinstalled Docker using the recommended method, you may still experience problems. This is because Snap's Docker uninstall process is incomplete, leaving remnants of the old installation which will corrupt future installations of Docker.

Luckily, there is an easy solution:

  1. Remove the Snap installation of Docker:
snap remove docker

  1. Install Docker using the official Docker installation steps

  2. To finish clean-up of the Snap uninstall process, reboot your machine:

reboot

Waiting for services to start

It can take several minutes for all backend services to come up and be in a healthy state.

If you see this message when accessing the Dashboard after waiting for several minutes, this likely means either the Dashboard cannot access the backend (eg a CORS misconfiguration or firewall setting), or a backend service is not running.

Check your browser's developer tools to confirm.

Browser developer tools: Console tab

If you see a Cross Origin Resource Sharing error, such as Access to fetch at '{...}' from origin '{...}' has been blocked by CORS policy, this likely confirms there's a CORS misconfiguration. If you deployed Sublime to a remote VPS, but haven't updated the backend's allowed CORS origins, you'll see this error. CORS origins are restricted by default for your security.

See step 2 of Manual Installation: Docker for instructions on how to update the CORS settings for your deployment.

If you see ERR_CONNECTION_REFUSED, this likely means the backend API is not running. Check the Docker logs (see above) for more information.

Browser developer tools: Network tab

See what status codes are being returned from the requests to /v1/health. This can be useful for debugging.

Backend not running

If your backend is not running after installation, then you may want to reset your installation by:

  • Wiping your Postgres volume (see below) without starting Sublime again
  • Removing your Sublime Platform directory: rm -rf ./sublime-platform
  • Follow installation steps again

Clear your local storage

If you're in a bad state (eg if you've wiped your deployment and started fresh, but still running into issues), you can try clearing your local storage from your browser's developer tools:

Out of disk space

If you run out of disk space while running Sublime Platform, you have a few options.

📘

After following any of the steps below, restart your Sublime deployment:

docker compose down && docker compose up

1. Freeing up Docker disk space

You can prune unused images to free up Docker disk resources.

Remove all unused images:

docker image prune

2. Expand the resources allocated to Docker

For macOS deployments / Docker Desktop, you can solve this by expanding Disk image size in Docker settings:

3. Expand the host file system

If the Docker resources aren't an issue, but your host has run out of disk space, then you'll need to expand your host file system volume.

For Ubuntu distributions, this is a good guide on how to expand your host's file system volume.

Wipe your data

❗️

THIS WILL WIPE ALL YOUR SUBLIME DATA STORED IN POSTGRES

Only follow the steps below if you are certain you don't need access to any data within your Sublime deployment.

  1. Navigate to the sublime-platform directory created during setup:
cd sublime-platform
  1. Stop the docker containers:
docker compose down

docker compose --profile letencrypt down
  1. Remove the docker containers:
docker compose rm

docker volume rm $(docker volume ls -f name=sublime-platform --format "{{.Name}})

If you wish to remove Sublime completely, you may remove the sublime-platform/ directory, and the cron job (crontab -e) if you configured automatic updates.

Updated about 1 month ago