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://sublime.security/install.sh | sh
Alternatively, you can follow our Manual Installation: Docker guide.
Requirements
Mailboxes | RAM | CPUs | Storage |
---|---|---|---|
10 | 8GB | 4 | 50GB |
100 | 16GB | 8 | 100GB |
600 | 32GB | 16 | 200GB |
- 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
- Linux (Tested on Ubuntu 18-22.10, Amazon Linux 2, CentOS 7, and Fedora 34-37)
- The following ports will need to be accessible when deployed remotely:
3000
: Used by the Sublime Dashboard8000
: Used by the Sublime API443
: If using SSL80
: If using SSL
- Docker version: 20.10.0 or greater
Rundocker version
to see your Docker version - Git version: 2.7.0 or greater
Rungit version
to see your Git version - docker compose version: 2.4.0 or greater
Rundocker 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
- Register your domain if you don't already have one, or use a subdomain.
- Create an A record to point to your VPS/host.
- Verify your A record has propagated. Run this in your terminal:
dig YOUR_DOMAIN A
2. Configure Sublime
- Navigate to your
sublime-platform
directory. - Run
cp certbot.env.example certbot.env
- Edit
certbot.env
with your domain and the email associated with it. - Create a file called
sublime.env
with the following contents (replaceYOUR_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.
- Ensure that ports 80 and 443 are open to the web. This is necessary for
certbot
to create your LetsEncrypt certs. - 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.
-
Navigate to your
sublime-platform
directory. -
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:
- Remove the Snap installation of Docker:
snap remove docker
-
Install Docker using the official Docker installation steps
-
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
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
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
no space left on device
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:
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
- Register a new subdomain
- Update your
certbot.env
andsublime.env
files with the new subdomain- 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.
- Navigate to the sublime-platform directory created during setup:
cd sublime-platform
- Stop the docker containers:
docker compose down
docker compose --profile letsencrypt down
- Remove the docker containers:
docker compose rm
- 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:
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 theX-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 servicebora-lite
: Async task service which is most commonly used for processing emailsscreenshot-service
: Converts email HTML to imagehydra
: 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 servicesredis
: Shared cachesublime3
: 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.
Updated 4 days ago