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://sublime.security/install.sh | sh

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

Requirements

• Supported architectures:
  • amd64 / x86_64
  • arm64 (including Apple Silicon -- M1/M2 Macs)
• Supported operating systems:
  • Linux (Tested on Ubuntu 18-22.10, Amazon Linux 2, CentOS 7, and Fedora 34-37)
    • Recommended: Ubuntu 22.10
  • macOS
• The following ports will need to be accessible when deployed remotely:
  • 3000: Used by the Sublime Dashboard
  • 8000: Used by the Sublime API
  • 443: If using SSL
  • 80: If using SSL
• Docker version: 20.10.0 or greater
  Run docker version to see your Docker version
  • Linux installation
  • macOS installation
• 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 deployment 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 Cloud-native deployment or Sublime Cloud, which can support any number of mailboxes.
• The Docker deployment is "polling" based, opposed to callback/subscription based, so there’s naturally at least a 15 second delay between polling intervals when checking for new messages that have arrived. You may see a longer delay with more mailboxes. The cloud-native deployments are callback-based (i.e. push instead of pull), and real-time.
• System updates bring the platform fully down, so mailboxes are not protected when standard updates are applied. Downtime for typical updates is usually short (less than a minute), but larger updates could take longer.
• Downloading the raw EML for unflagged messages isn't currently supported due to raw message retention limitations.
• Audit log export to S3 currently isn't supported.
• Message analysis time is slower than cloud-native deployments, and there is no auto-scaling. Inference for some machine learning models are most performant on GPUs, which currently isn't supported via our Docker containers.
• Enterprise monitoring is more limited for Docker based deployments.
• No built-in backups or instrumentation for backups.

SSL

To enable SSL for your installation via Nginx and certbot, follow the steps below.

1. Set up your domain

1. Register your domain if you don't already have one, or use a subdomain.
2. Create an A record to point to your VPS/host.
3. Verify your A record has propagated. Run this in your terminal: dig YOUR_DOMAIN A

2. Configure Sublime

1. Navigate to your sublime-platform directory.
2. Run cp certbot.env.example certbot.env
3. Edit certbot.env with your domain and the email associated with it.
4. Create a file called sublime.env with the following contents (replace YOUR_DOMAIN_HERE with the domain you registered in step 1).

CORS_ALLOW_ORIGINS=https://YOUR_DOMAIN_HERE
BASE_URL=https://YOUR_DOMAIN_HERE
DASHBOARD_PUBLIC_BASE_URL=https://YOUR_DOMAIN_HERE
API_PUBLIC_BASE_URL=https://YOUR_DOMAIN_HERE

Note: The URLs for these environment variables should not include a port. For example, if you're hosting Sublime at sublime.example.com, the configured URLs should be https://sublime.example.com, without any port.

6. Ensure that ports 80 and 443 are open to the web. This is necessary for certbot to create your LetsEncrypt certs.
7. Re-run the install script: clone_platform=false ./install-and-launch.sh

How to update

📘

Automatic updates

If you deployed Sublime with one of our scripts, you may have enabled automatic updates (using Cron), which run nightly. If you want to manually update your Sublime Platform then follow the steps below.

1. Navigate to your sublime-platform directory.

2. Copy and paste the appropriate shell commands below depending on how you setup Sublime. This will update your Github repo, then pull the latest images from Docker Hub and restart your instances:

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

docker compose --profile letsencrypt down; git pull; docker compose --profile letsencrypt pull --include-deps; docker compose --profile letsencrypt 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

2. Install Docker using the official Docker installation steps

3. 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:

console

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:

View: https://user-images.githubusercontent.com/11003450/212777369-380b08f3-c870-425f-a20c-f3350f108c4f.gif

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

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

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

2. Stop the docker containers:

docker compose down

docker compose --profile letsencrypt down

3. Remove the docker containers:

docker compose rm

4. Wipe the Sublime docker volumes:

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.

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:

Bash

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.

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.

Deploying to AWS EC2

If you deploy the Docker deployment to EC2, you must allow ports 3000 and 8000 ingress in the VPC's security group.

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. You can change these settings in your Account page.

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.