Deploy Sublime Platform using Docker

Estimated time: < 15 minutes

Sublime Platform can be deployed locally on a laptop or remotely to a VPS or VM using Docker.

Setup

One-line install

Copy the command below to the clipboard, then paste it into a bash terminal on macOS or Linux:

curl -sL https://sublimesecurity.com/install.sh | bash

Alternatively, you can follow our Manual Installation: Docker guide.

Requirements

MailboxesRAMCPUsStorage
108GB450GB
10016GB8100GB
100032GB16200GB
  • Supported operating systems:
    • Linux (Ubuntu 20.04 or greater)
    • macOS (11.0 or greater)
  • The following ports will need to be accessible when deployed remotely:
    • 3000: Used by the Sublime Dashboard
    • 8000: Used by the Sublime API
  • Docker version: 20.10.0 or greater
    Run docker version to see your Docker version
  • Git version: 2.7.0 or greater
    Run git version to see your Git version
  • docker compose version: 2.4.0 or greater
    Run docker compose version to see your Docker Compose version
    • Linux: comes installed with Docker engine but you can also do the standalone installation
    • macOS: comes installed with Docker Desktop

Docker limitations

This Docker deployment is intended for small-medium size deployments or for testing purposes, and should not be used for more than 600 active mailboxes.

If you'd like to activate more than 600 mailboxes, use the AWS CloudFormation deployment or Sublime Cloud, which can support any number of mailboxes.

How to update

📘

Automatic updates

If you installed your Sublime Platform with one of our scripts then automatic updates have already been configured to occur nightly. If you want to manually update your Sublime Platform then follow the steps below.

  1. Navigate to your sublime-platform directory.

  2. Update your Github repo, then pull the latest images from Docker Hub and restart your instances:

git pull; docker compose pull; docker compose up -d;

Troubleshooting

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

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

Docker logs errors

Run the following command to look for errors:

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

If you see the following error: 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.

If you see the following error: 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.

If you see the following error: no space left on device

See out of disk space

📘

Live tail Docker logs

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

docker compose logs -f

Docker Compose errors

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.

Error: no space left on device

See out of disk space

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:

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
  1. Remove the docker containers:
docker compose rm
  1. Wipe the Sublime docker volumes:
docker volume rm $(docker volume ls -f name=sublime-platform --format "{{.Name}}")

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:

2700

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.

Using a proxy

If you want to set up a proxy in front of Sublime (e.g., nginx), it's important to note that Sublime's frontend and API are served on different ports when using Docker Compose. The frontend is served on port 3000 while the API is served on port 8000.

This means you should configure your proxy to proxy all API requests (requests with paths starting with /v0/ or /v1/) to port 8000 and all other requests to port 3000. Allow requests to port 8110 to pass through.

Also be certain to update the configuration in your sublime.env file to reflect the hostname for your proxy. See step 2 of Manual Installation: Docker for more information.

By default for security reasons, any Sublime features which leverage client IP address (e.g. IP Allow List and Audit Log) will prefer the using the first value from the X-Forwarded-For header.

  • If you're not using a Proxy, you may add IP_DETECTION=REMOTE_ADDR to strictly use the remote address and ignore the header.
  • You may also set IP_DETECTION=X-FORWARDED-TRUST-LAST to prefer using last value of the X-Forwarded-For header.

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.

Usage data

Basic information like version, error logs, and high-level usage metrics are shared with the Sublime Team so we can troubleshoot issues, provide support, and make Sublime better for you and the community. If you'd like to opt-out of any of this, let us know via email or Slack. We're working on making this more configurable before Sublime becomes Generally Available.

Error logs are sent to Sentry

Docker services

These are the Docker containers that are spun up when running Docker Compose:

  • Backend services:
    • mantis: API service
    • bora-lite: Async task service which is most commonly used for processing emails
    • screenshot-service: Converts email HTML to image
    • hydra: Machine learning (ML) service that powers a number of detection capabilities
  • Frontend services:
    • dashboard: Serves the dashboard frontend
  • Infrastructure: posgres, redis, sublime3
    • postgres: DB instance used by backend services
    • redis: Shared cache
    • sublime3: A local version of AWS S3
  • Strelka: strelka-frontend, strelka-backend, strelka-manager, strelka-coordinator
    • A real-time, container-based file scanning system used for threat hunting, threat detection, and incident response created by Target

Support

If you run into any issues or have questions, send us an email or post in the Slack community.