Self-Hosting with Docker

Learn how to configure and deploy SpaceDF Platform with Docker.

Docker is the easiest way to start self-hosting SpaceDF. You can usually get everything running in under 30 minutes.

Contents

Before you begin

Before setting up SpaceDF, you should be familiar with some basic concepts. You do not need to be an expert, but you should understand:

• Basic Linux server usage (connecting to a server, running commands)
• How Docker and Docker Compose work at a high level
• Basic networking concepts such as ports and firewalls

Make sure the following tools are installed on your machine or server:

• Git  – used to download the SpaceDF source code
• Docker  – used to run SpaceDF and its services

Install Docker based on your operating system:

• Linux server or VPS: Install Docker Engine  and Docker Compose 
• Linux desktop: Install Docker Desktop 
• macOS: Install Docker Desktop 
• Windows: Install Docker Desktop 

Once these requirements are met, you are ready to start installing SpaceDF.

System requirements

Minimum requirements for running all SpaceDF Platform components, suitable for development and small to medium production workloads:

Installing SpaceDF

Follow the steps below to install and run SpaceDF on your machine.

# Get the code
git clone https://github.com/Space-DF/spacedf-core.git
 
# Make your new spacedf project directory
mkdir spacedf-project
 
# Tree should look like this
# .
# ├── spacedf-core
# └── spacedf-project
 
# Copy the compose files over to your project
cp -rf spacedf-core/docker-compose.yml spacedf-project
 
# Copy the fake env vars
cp spacedf-core/.env.example spacedf-project/.env
 
# Switch to your project directory
cd spacedf-project
 
# Pull the latest images
docker compose pull

Configuring and securing SpaceDF

The .env.example file includes sample passwords and keys for reference only. You must replace these values before starting SpaceDF in a self-hosted environment.

Quick setup (experimental)

To generate and apply all secrets at once you can run:

sh ./utils/generate-keys.sh

The script is experimental, so review the output before proceeding and also check .env after it’s updated by the script.

Alternatively, configure all secrets manually as follows.

Configuring Environment Variables

This section explains how to configure the required environment variables in the .env file before starting SpaceDF.

Open the .env file using a text editor (for example: VS Code, Nano, or Notepad).

Services Configuration

These environment variables configure the backend services that power the self-hosted SpaceDF server.
Backend services include APIs, messaging, databases, and integrations required to run the core system.

RabbitMQ credentials

RabbitMQ is used by SpaceDF to handle background tasks and message processing.

RABBITMQ_DEFAULT_USER=default
RABBITMQ_DEFAULT_PASS=password

• RABBITMQ_DEFAULT_USER - The username SpaceDF uses to connect to RabbitMQ.
• RABBITMQ_DEFAULT_PASS - The password for the RabbitMQ user above.

Authentication (JWT)

SpaceDF uses JSON Web Tokens (JWT) to authenticate users and secure API requests.

You must set a private key and a public key before starting SpaceDF.

openssl genrsa -out jwt_private.pem 2048
openssl rsa -in jwt_private.pem -pubout -out jwt_public.pem

JWT_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----...
JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...

• JWT_PRIVATE_KEY - Signs authentication tokens (Keep this key secret.).

• JWT_PUBLIC_KEY - Verifies authentication tokens. This key can be shared with other services if needed.

Make sure the keys are pasted correctly and not broken across lines.

Google OAuth

Google OAuth allows users to sign in to SpaceDF using their Google account.

To enable Google login, you need to create OAuth credentials in the Google Cloud Console and set the values below in your .env file.

# Replace with your own values.
GOOGLE_CALLBACK_URL=https://spacedf.example.com/auth/google/callback
GOOGLE_CLIENT_ID=1234567890-abcxyz.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret

• GOOGLE_CALLBACK_URL - The URL Google redirects users back to after successful login.
• GOOGLE_CLIENT_ID - Identifies your application to Google.
• GOOGLE_CLIENT_SECRET - A private key used by SpaceDF to securely communicate with Google (Keep this value secret.)

How to get Google OAuth credentials

Apple OAuth (Coming Soon)

Apple sign-in support is planned but not yet supported in SpaceDF.

# Apple OAuth (reserved for future use)
APPLE_CLIENT_ID=__APPLE_CLIENT_ID__
APPLE_CLIENT_SECRET=__APPLE_CLIENT_SECRET__
APPLE_CLIENT_KEY=__APPLE_CLIENT_KEY__
APPLE_CERTIFICATE_KEY=__APPLE_CERTIFICATE_KEY__

Auth Service

The Auth Service is responsible for user authentication, authorization, and tenant management in SpaceDF.

Set the following values in your .env file.

# Replace with your own values.
AUTH_POSTGRES_PASSWORD=__AUTH_POSTGRES_PASSWORD__
AUTH_SECRET_KEY=__AUTH_SECRET_KEY__
DEFAULT_TENANT_HOST=__DEFAULT_TENANT_HOST__
ROOT_API_KEY=__ROOT_API_KEY__

• AUTH_POSTGRES_PASSWORD - The password used by the Auth Service to connect to its PostgreSQL database. (Use a strong and unique password.)
• AUTH_SECRET_KEY - A secret key used to sign and validate authentication-related data. (Keep this value private.)
• DEFAULT_TENANT_HOST - The default domain or host assigned to the initial tenant. This is usually your main application domain.
• ROOT_API_KEY - A master API key with full access to the Auth Service. Used for administrative or internal operations only.

Secret keys: Generate secure random values for secret keys:

openssl rand -hex 32

Use the generated value for:

AUTH_SECRET_KEY=generated_secret_value
ROOT_API_KEY=generated_root_api_key

Default tenant host

Set this to the domain or host where SpaceDF will be accessed:

DEFAULT_TENANT_HOST=app.spacedf.example

S3 Service

The S3 Service is used by SpaceDF to store files such as uploads, assets, and generated data. This setup commonly uses Amazon S3 or any S3-compatible storage.

How to configure

# Replace with your own values.
AWS_ACCESS_KEY_ID=AKIAXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXX
AWS_STORAGE_BUCKET_NAME=spacedf-storage
AWS_REGION=ap-southeast-1

• AWS_ACCESS_KEY_ID - The access key used by SpaceDF to authenticate with S3.
• AWS_SECRET_ACCESS_KEY - The secret key paired with the access key above. (Keep this value private)
• AWS_STORAGE_BUCKET_NAME - The name of the S3 bucket where SpaceDF stores files.
• AWS_REGION - The AWS region where the S3 bucket is located. (e.g., us-east-1, ap-southeast-1).

Using S3-compatible providers

If you are using an S3-compatible service (e.g., MinIO, DigitalOcean Spaces):

• Use the provider’s access key and secret
• Set the appropriate bucket name and region

Radis

Redis is used by SpaceDF for caching and fast data access.

Set the Redis connection URL in the .env file.

# Replace with your own values.
REDIS_HOST="redis://redis:6379/1"

• redis:// — Connection protocol
• redis — Redis service name (default in Docker)
• 6379 — Default Redis port
• /1 — Redis database number

Dashboard Service

The Dashboard Service provides the web interface for managing SpaceDF, including administration and monitoring features.

Database password

Choose a strong password for the Dashboard Service database:

# Replace with your own values.
DASHBOARD_POSTGRES_PASSWORD=change_this_to_a_secure_password

DASHBOARD_POSTGRES_PASSWORD - The password used by the Dashboard Service to connect to its PostgreSQL database. (Use a strong and unique password.)

Secret key: Generate a secure random value:

openssl rand -hex 32

Set it in your .env file:

# Replace with your own values.
DASHBOARD_SECRET_KEY=generated_secret_value

DASHBOARD_SECRET_KEY - A secret key used to sign and protect dashboard-related sessions and data. (Keep this value private.)

Device Service

The Device Service manages devices, device data, and communication with telemetry-related services in SpaceDF.

Database password

Choose a strong password for the Device Service database:

# Replace with your own values.
DEVICE_POSTGRES_PASSWORD=change_this_to_a_secure_password

DEVICE_POSTGRES_PASSWORD - The password used by the Device Service to connect to its PostgreSQL database. (Use a strong and unique password.)

Secret key: Generate a secure random value:

openssl rand -hex 32

Set it in your .env file:

# Replace with your own values.
DEVICE_SECRET_KEY=generated_secret_value

DEVICE_SECRET_KEY - A secret key used to sign and protect device-related data and requests. (Keep this value private.)

Telemetry service URL Set this to the URL where the Telemetry Service is running.

Example: Telemetry service running in Docker

# Replace with your own values.
TELEMETRY_SERVICE_URL=http://telemetry-service:8080

Example: External telemetry service

# Replace with your own values.
TELEMETRY_SERVICE_URL=https://telemetry.spacedf.example

EMQX Service

EMQX is the MQTT broker used by SpaceDF to handle device messaging and real-time communication.

Choose a username and a strong password:

# Replace with your own values.
EMQX_HOST=http://emqx:18083/api/v5
EMQX_USERNAME=spacedf
EMQX_PASSWORD=change_this_to_a_secure_password

• EMQX_HOST - The base URL of the EMQX Management API used by SpaceDF. This is typically the EMQX service running inside Docker.
• EMQX_USERNAME - The username SpaceDF uses to authenticate with the EMQX broker.
• EMQX_PASSWORD - The password for the EMQX user above. (Use a strong and unique password.)

Broker Bridge Service

The Broker Bridge Service connects SpaceDF to an external MQTT broker or bridges messages between brokers.

Broker credentials

# Replace with your own values.
MQTT_BROKER_BRIDGE_USERNAME=bridge-user
MQTT_BROKER_BRIDGE_PASSWORD=change_this_to_a_secure_password

• MQTT_BROKER_BRIDGE_USERNAME - The username used to authenticate with the external MQTT broker.
• MQTT_BROKER_BRIDGE_PASSWORD - The password for the broker bridge user. (Keep this value private.)

MQTT topics

Specify one or more topics, separated by commas.

# Replace with your own values.
MQTT_TOPICS=devices/+/telemetry,devices/+/status

MQTT_TOPICS - A list of MQTT topics that SpaceDF subscribes to or bridges.

AWS to access to SES service

SpaceDF uses email services to send system emails such as account verification, password resets, and notifications.

This setup commonly uses AWS Simple Email Service (SES), but can be adapted to other SMTP-compatible providers.

Set the following values in your .env file.

# Replace with your own values.
EMAIL_BACKEND=ses
EMAIL_HOST=email-smtp.us-east-1.amazonaws.com
EMAIL_PORT=587
EMAIL_USE_TLS=true
EMAIL_HOST_USER=AKIAXXXXXXXX
EMAIL_HOST_PASSWORD=XXXXXXXXXXXXXXXX
DEFAULT_FROM_EMAIL=no-reply@spacedf.example

• EMAIL_BACKEND - Specifies the email provider. Use ses when sending email through AWS SES.
• EMAIL_HOST - The SMTP endpoint provided by AWS SES (e.g. email-smtp.us-east-1.amazonaws.com).
• EMAIL_PORT - The SMTP port used to send email. Common values: 587 (TLS) or 465 (SSL).
• EMAIL_USE_TLS - Enables secure email delivery using TLS. Recommended value: true.
• EMAIL_HOST_USER - The SMTP username generated by AWS SES.
• EMAIL_HOST_PASSWORD - The SMTP password generated by AWS SES (Keep this value secret)
• DEFAULT_FROM_EMAIL - The sender email address shown to users.

How to get AWS SES credentials

MPA Service

The MPA Service connects SpaceDF to an MQTT broker to receive and publish messages for application-level processing.

Example: MQTT broker running in Docker

# Replace with your own values.
MQTT_BROKER=emqxl
MQTT_PORT=1883
MQTT_USERNAME=mpa
MQTT_PASSWORD=change_this_to_a_secure_password
MQTT_CLIENT_ID=spacedf-mpa
MQTT_TOPIC=devices/+/events

• MQTT_BROKER - The hostname or IP address of the MQTT broker.
• MQTT_USERNAME - The username used to authenticate with the MQTT broker.
• MQTT_PASSWORD - The password for the MQTT user. (Keep this value private.)
• MQTT_PORT - The port used to connect to the MQTT broker (e.g., 1883 for plain TCP, 8883 for TLS).
• MQTT_CLIENT_ID - A unique client identifier for the MPA Service when connecting to MQTT.
• MQTT_TOPIC - The MQTT topic the MPA Service subscribes to.

Bootstrap Service

The Bootstrap Service is responsible for initial system setup and cross-service coordination when SpaceDF starts.

Service host

Set this to the URL where the Bootstrap Service is reachable.

# Replace with your own values.
HOST=http://localhost:8000

For production, use your public domain:

# Replace with your own values.
HOST=https://api.spacedf.example

HOST - The public base URL where the Bootstrap Service is accessible. This is used by other services to communicate with it.

CORS origins

List all frontend origins that should be allowed to access the service. Separate multiple values with commas.

Development (local)

CORS_ALLOWED_ORIGINS=http://localhost,http://localhost:3000,http://localhost:3001

Production

# Replace with your own values.
CORS_ALLOWED_ORIGINS=https://app.spacedf.example,https://admin.spacedf.example

CORS_ALLOWED_ORIGINS - A comma-separated list of allowed origins for cross-origin requests. This controls which frontend domains can access the Bootstrap Service.

Only include domains you trust. Avoid using wildcards (*) in production.

Secret key: Generate a secure random value:

openssl rand -hex 32

Set it in your .env file:

# Replace with your own values.
BOOTSTRAP_SECRET_KEY=generated_secret_value

BOOTSTRAP_SECRET_KEY - A secret key used to secure internal Bootstrap operations. (Keep this value private.)

Organization Initialization

These settings are used to create the initial organization and owner account when SpaceDF starts for the first time. This step runs only during the first startup.

# Replace with your own values.
ORG_NAME=SpaceDF
ORG_SLUG=spacedf
OWNER_EMAIL=admin@spacedf.example
OWNER_PASSWORD=change_this_to_a_secure_password

• ORG_NAME - The display name of your organization.
• ORG_SLUG - A short, URL-friendly identifier for the organization (lowercase, no spaces).
• OWNER_EMAIL - The email address of the initial organization owner.
• OWNER_PASSWORD - The password for the owner account. (Use a strong and secure password.)

Admin Portal Configuration

The Admin Portal is used for system-level and organization-level administration.

This application is typically accessed by platform administrators, not end users.

Configure these environment variables to connect the Admin Portal to backend services and authentication providers.

Authentication

Generate NextAuth secret

Open the following link  in your browser to generate a secure random secret:

Copy the generated value and set it in your .env file:

# Replace with your own values.
PORTAL_NEXTAUTH_SECRET=4f7c2a9e8d1b6c3f0a...

PORTAL_NEXTAUTH_SECRET - A secret key used by NextAuth to encrypt sessions and tokens. (Keep this value private.)

Admin Portal URL

Development

HOST_FRONTEND_ADMIN=http://localhost:3001
PORTAL_NEXTAUTH_URL=http://localhost:3001

Production

HOST_FRONTEND_ADMIN=https://admin.spacedf.example
PORTAL_NEXTAUTH_URL=https://admin.spacedf.example

• HOST_FRONTEND_ADMIN - The public URL where the Admin Portal is accessible.
• PORTAL_NEXTAUTH_URL - The base URL used by NextAuth for redirects and callbacks.
  This value should match the Admin Portal public URL.

API Access

Using Docker

PORTAL_AUTH_API=http://haproxy:3000

External API

# Replace with your own values.
PORTAL_AUTH_API=https://api.spacedf.example

PORTAL_AUTH_API - The backend API endpoint used by the Admin Portal for authentication.
This typically points to the internal API gateway or load balancer.

References

Use the official documentation below if you need more details about NextAuth behavior or advanced configuration:

• NextAuth.js Documentation 
• NextAuth Environment Variables 
• NextAuth Security Guide 

Dashboard Configuration

This section configures the SpaceDF Dashboard, the main web interface used for daily operations, device monitoring, and data visualization.

Authentication

Generate NextAuth secret

Open the following link  in your browser to generate a secure random secret:

Copy the generated value and set it in your .env file:

# Replace with random secret.
DASHBOARD_NEXTAUTH_SECRET=4f7c2a9e8d1b6c3f0a...
 
# The public URL where the Dashboard is accessible.
DASHBOARD_NEXTAUTH_URL=http://localhost:3000

• DASHBOARD_NEXTAUTH_SECRET - A secret key used by NextAuth to encrypt sessions and tokens. (Keep this value private.)
• DASHBOARD_NEXTAUTH_URL - The public URL where the Dashboard is accessible.
  This value is used for redirects and callbacks.

API Access

Using Docker

DASHBOARD_AUTH_API=http://haproxy:3000
 
# This key must match the value configured on the backend.
SPACE_API_KEY=__SPACE_API_KEY__

External API

# Replace with your own values.
DASHBOARD_AUTH_API=https://api.spacedf.example
 
# This key must match the value configured on the backend.
SPACE_API_KEY=__SPACE_API_KEY__

Map Services

The Dashboard uses MapTiler as a map service to resolve location names from coordinates and support location-based features.

# Replace with your API Key.
MAPTILER_API_KEY=__MAPTILER_API_KEY__

How to get a MapTiler API key

MQTT (Real-time Data)

The Dashboard connects to MQTT to receive real-time device data.

Recommended values
Development

DASHBOARD_MQTT_PROTOCOL=ws
DASHBOARD_MQTT_PORT=8883
DASHBOARD_MQTT_BROKER=emqx.localhost:8000

Production

# Use wss (secure WebSocket) in production.
DASHBOARD_MQTT_PROTOCOL=wss
DASHBOARD_MQTT_PORT=443
DASHBOARD_MQTT_BROKER=emqx.example.com

• DASHBOARD_MQTT_USERNAME / DASHBOARD_MQTT_PASSWORD - Credentials used by the Dashboard to connect to the MQTT broker.
• DASHBOARD_MQTT_PROTOCOL - Protocol used for MQTT connections.
  Use ws (WebSocket) for browser-based clients.
• DASHBOARD_MQTT_PORT - Port exposed by the MQTT broker for WebSocket connections.
• DASHBOARD_MQTT_BROKER - Host and port of the MQTT broker accessible from the browser.

References

• NextAuth.js Documentation 
• MapTiler Documentation 
• MQTT over WebSocket 

Starting and Stopping

This section explains how to start, check, and stop SpaceDF services using Docker Compose.

Starting the services

From the directory that contains your docker-compose.yml file, run:

# Start all services in the background
docker compose up -d

Docker will start all SpaceDF services in detached mode.

Checking service status

After starting, you can check the status of all services:

docker compose ps

Within a minute, most services should show a status similar to:

Up (healthy)

Troubleshooting startup issues

If a service shows a status like created or does not become Up, check its logs to see what went wrong.

For example, to view logs for a specific service:

docker compose logs analytics

Review the logs for errors such as missing environment variables or connection issues.

Stopping the services

To stop all running SpaceDF services, run:

docker compose down

This stops and removes the containers but keeps your data volumes intact.

Accessing SpaceDF Services

After all services are running, you can access SpaceDF through the web interfaces and backend APIs using the URLs below.

Updating

SpaceDF publishes stable updates for the Docker Compose setup on a regular basis. To update your self-hosted deployment, pull the latest changes from the repository and restart the services.

Updating services requires restarting containers and may cause temporary downtime.

General update process

In most cases, this is enough to apply the latest updates.

Updating individual services (advanced)

You can run a specific version of a service by changing its Docker image tag in the docker-compose.yml file.

Update or rollback a single service

For example, if you want to update or roll back the Dashboard service:

 image: ghcr.io/space-df/spacedf-web-app:v2026.01.21

 docker compose pull
 docker compose down
 docker compose up -d

The service will restart using the specified version.

Notes on downtime

• Services must be restarted to apply updates
• Active users may experience brief downtime
• Consider performing updates during low-traffic periods

Staying up to date

• To track changes, fixes, and new features, refer to:
  • SpaceDF release notes
• The self-hosting changelog in the repository

Uninstalling

Stop and remove services

From the directory that contains your docker-compose.yml file, run:

# Stop all services and remove containers and volumes
docker compose down -v

This command stops all SpaceDF services and removes all associated Docker volumes.

(Optional) Remove remaining data manually

In some cases, you may want to ensure all data directories are fully removed.

Remove database data

rm -rf volumes/db/data

Remove storage data

rm -rf volumes/storage

What gets removed

• All SpaceDF services
• All databases and stored data
• All uploaded files and assets

After these steps, SpaceDF is completely removed from your system.

Demo

Need Help?

• Community Forum  - Get help from the SpaceDF community
• Discord Server  - Real-time chat with other users and developers
• Documentation - Comprehensive guides and tutorials
• Professional Support - Enterprise support with SLA guarantees

Ready to start? Create your SpaceDF account  and begin tracking your devices in minutes!