Advanced Setup with Docker

This guide covers detailed configuration, customization, and operational topics for running SpaceDF with Docker Compose.

If you only want to get SpaceDF running quickly with default settings, see Quick Start.

Contents

Prerequisites

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.

 
# Make your new spacedf project directory
mkdir spacedf-project
 
# Get the code
cd spacedf-project
git clone https://github.com/Space-DF/spacedf-core.git
 
# Switch to your project directory
cd spacedf-core
 
# Initialize submodules (Important!)
git submodule update --init --recursive
 
# Copy the env vars
cp .env.example .env
 
# Pull the latest images
docker compose pull

Configuration & Security

Before starting SpaceDF, you need to set up the environment variables.

# Switch to your project directory
cd spacedf-core
 
# Copy the env vars
cp .env.example .env

Configuring Environment Variables

Now that you have your .env file, you need to configure the settings.

Backend Services

This section configures the connections between SpaceDF and your infrastructure (such as your database and cache).

These settings are the backbone of your server.

RabbitMQ Configuration

SpaceDF uses RabbitMQ to handle background tasks and internal messaging.
You need to set up credentials so the system can connect to the message queue.

Set your credentials You can choose any username and password you want.

RABBITMQ_DEFAULT_USER="your_secure_username"
RABBITMQ_DEFAULT_PASS="your_secure_password"

Variable Details:

• RABBITMQ_DEFAULT_USER: The username for the connection.
• RABBITMQ_DEFAULT_PASS: The password for the connection.

Authentication (JWT)

SpaceDF uses JSON Web Tokens (JWT) to secure API requests. You need to generate a specific key pair for this to work.

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Copy Private Key
pbcopy < private_key.pem
 
# Copy Public Key
pbcopy < public_key.pem

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Copy Private Key
cat private_key.pem | clip
 
# Copy Public Key
cat public_key.pem | clip

openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Show Private Key -> Copy the output
cat private_key.pem
 
# Show Public Key -> Copy the output
cat public_key.pem

Example of correct formatting:

# ✅ CORRECT (Quotes are used)
JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA...
... (your long key content) ...
...O4zXk=
-----END RSA PRIVATE KEY-----"
 
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG...
... (your long key content) ...
...IDAQAB
-----END PUBLIC KEY-----"

Google OAuth

Enable this to allow users to sign in to SpaceDF using their Google accounts.

You will need to generate credentials in the Google Cloud Console.

1. Get Credentials

Follow these steps to create your Client ID and Secret.

3

Create Credentials

• Go to APIs & Services > Credentials.
• Click + Create Credentials and select OAuth client ID.
• Application type: Select Web application.
• Name: Enter a name (e.g., “SpaceDF Self-Hosted”).

 # Production
 https://your-domain.com/auth/google/callback
 
 # Development
 http://localhost:3000/auth/google/callback

2. Update Environment

Open your .env file and paste the values you just obtained.

Connection Settings

# 1. The URL you configured in Step 4 above
GOOGLE_CALLBACK_URL="http://localhost:3000/auth/google/callback"
 
# 2. The Client ID from Step 5
GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
 
# 3. The Client Secret from Step 5
GOOGLE_CLIENT_SECRET="your-client-secret"

Variable Details

• GOOGLE_CALLBACK_URL - Where Google sends the user after login. Must match the URI in Google Cloud Console exactly.
  
• GOOGLE_CLIENT_ID - The public identifier for your app.
  
• GOOGLE_CLIENT_SECRET - The secret key to authenticate your app. Keep this private.

Apple OAuth

Support for “Sign in with Apple” is currently in development. It is not enabled in this version of SpaceDF.

# Apple OAuth (Reserved for future updates)
# Leave these lines commented out for now:
# APPLE_CLIENT_ID=
# APPLE_CLIENT_SECRET=
# APPLE_CLIENT_KEY=
# APPLE_CERTIFICATE_KEY=

Auth Service

The Auth Service manages user logins and security. You need to configure its database connection and domain settings.

1. Security Credentials

Set up the password for the database and the encryption key for sessions.

openssl rand -hex 32

# 1. Database Password (Make sure it is strong)
AUTH_POSTGRES_PASSWORD=your_secure_db_password
 
# 2. Secret Key (Paste the output from Step 1)
AUTH_SECRET_KEY=paste_generated_key_here

2. Tenant Configuration

This defines the main domain where your application runs.

DEFAULT_TENANT_HOST=localhost

DEFAULT_TENANT_HOST=your-domain.com

S3 Service

SpaceDF uses Amazon S3 to store uploaded files, assets, and generated data.

You need to provide IAM Credentials so SpaceDF can access your storage securely.

If you do not already have an AWS account, create one at:
https://signin.aws.amazon.com/signup?request_type=register 

1. Create an S3 Bucket

This is the “container” where your files will be stored.

2

Create a new bucket
Click the orange Create bucket button. Configure the following:

• Bucket name: Enter a globally unique name (e.g., spacedf-storage-yourname).
• AWS Region: Choose a region close to your users (e.g., Sydney (ap-southeast-2))
• Block Public Access: Keep “Block all public access” checked (Enabled) for security. SpaceDF handles access control internally.

Refer: Official AWS Guide on Creating Buckets 

2. Create IAM Credentials

Now you need to create a “Service User” that has permission to read/write to that bucket.

Create IAM credentials

4

Generate Keys

• Click on the user name you just created.
• Go to the Security credentials tab
• Scroll down to Access keys and click Create access key.
• Select Application running outside AWS
• Click Next -> Click Create access key.

Refer: Managing Access Keys in IAM 

3. Update Environment

Open your .env file and fill in the values from the previous steps.

# AWS S3 Configuration
AWS_ACCESS_KEY_ID="your_access_key_id_from_phase_2"
AWS_SECRET_ACCESS_KEY="your_secret_key_from_phase_2"
 
AWS_STORAGE_BUCKET_NAME="your_bucket_name_from_phase_1"
AWS_REGION="your_region_code"

Variable Details:

• AWS_ACCESS_KEY_ID: The ID connecting to your IAM user.
• AWS_SECRET_ACCESS_KEY: The password for the IAM user.
• AWS_STORAGE_BUCKET_NAME: The name of your bucket (e.g., my-app-storage).
• AWS_REGION: The code for your region.

Redis

SpaceDF uses Redis for caching data and handling background tasks (like sending emails).

1. Default Configuration (Docker)

If you are installing SpaceDF using the standard Docker setup, you do not need to change this.

REDIS_HOST="redis://redis:6379/1"

2. External Configuration (Advanced)

Only change the value if your Redis runs on a different server (e.g., AWS ElastiCache, DigitalOcean Managed Redis).

Example:

# Example for external Redis with password
REDIS_HOST="redis://:mypassword123@192.168.1.50:6379/0"

3. Connection Details

Breakdown of the connection string components:

Service Credentials

The following services (Dashboard & Device) operate independently. Each requires its own Database Password and unique Secret Key to function securely.

1. Generate Secret Keys Run this command twice to generate two different keys:

openssl rand -hex 32

2. Update .env Update the values for both the Dashboard and Device services.

# --- Dashboard Service ---
# Password for Dashboard Database
DASHBOARD_POSTGRES_PASSWORD=your_dashboard_db_password
# Secret Key for Dashboard (Paste generated key 1)
DASHBOARD_SECRET_KEY=your_dashboard_secret_key
 
# --- Device Service ---
# Password for Device Database
DEVICE_POSTGRES_PASSWORD=your_device_db_password
# Secret Key for Device (Paste generated key 2)
DEVICE_SECRET_KEY=your_device_secret_key

Telemetry service

This section configures the high-performance components responsible for handling real-time device data.

1. Service URL This variable points to the internal Docker container that processes data.

# Default (recommended)
TELEMETRY_SERVICE_URL=http://telemetry:8080

2. TimescaleDB Password Define the password for the time-series database where all sensor data is stored.

# Default: postgres
# ⚠️ CHANGE THIS for Production!
TIMESCALEDB_PASSWORD=postgres

When to change this?

Only modify this value if you have manually customized the docker-compose.yml file to run the Telemetry service on a different port or server.

EMQX Service

EMQX is the core engine that handles real-time messages from your devices. SpaceDF needs to connect to the EMQX Management API to control it.

1. API Connection (Internal) Use the default value if you are running SpaceDF via Docker.

EMQX_HOST=http://emqx:18083/api/v5

2. Admin Credentials Define the username and password SpaceDF will use to log in to EMQX.

EMQX_USERNAME=your_secure_username
EMQX_PASSWORD=your_secure_password

Broker Bridge Service

The Bridge Service acts as a listener. It connects to the MQTT Broker to receive device data and forward it to SpaceDF.

1. Broker Authentication

Enter the credentials required to connect to the MQTT Broker (usually the same credentials used for EMQX clients).

MQTT_BROKER_BRIDGE_USERNAME=your_bridge_username #Default BrokerBridgeService
MQTT_BROKER_BRIDGE_PASSWORD=your_bridge_password

2. Topic Subscription Define which MQTT topics SpaceDF should listen to.

This value is pre-configured in your .env.example file. You should simply use the default value provided.

# ⚠️ DO NOT EDIT - Use the default value from .env.example
MQTT_TOPICS="tenant/+/transformed/device/location"

Email Service (AWS SES)

SpaceDF uses AWS SES (Simple Email Service) to send account verification emails, password resets, and notifications.

1. Setup & Verify

Before sending emails, you must tell AWS which email address or domain you own.

Refer: AWS Guide on Verifying Identities 

2. Get SMTP Credentials

Refer: AWS Guide on Obtaining SMTP Credentials 

3. Update Environment

Update the .env file with the SMTP credentials you just created.

# Acount AWS to access to SES service
EMAIL_HOST_USER=AKIA... #(Your SMTP Username)
EMAIL_HOST_PASSWORD=BAj... #(Your SMTP Password)
DEFAULT_FROM_EMAIL="no-reply@yourdomain.com"

Variable Details:

• EMAIL_HOST_USER: The username specifically generated for SMTP (starts with AKIA... usually).
• EMAIL_HOST_PASSWORD: The long secret string for SMTP authentication.
• DEFAULT_FROM_EMAIL: The email address that will appear as the sender (Must be verified in Phase 1).

MPA Service

The MPA Service connects to the MQTT Broker to process application events. It acts as a client that listens for device messages.

Configuration

Update the .env file with the connection details below.

# --- Connection Settings ---
# Hostname (Use 'emqx' if running inside Docker)
MQTT_BROKER=emqx
# Port (1883 for TCP, 8883 for SSL/TLS)
MQTT_PORT=1883
# Unique name for this client
MQTT_CLIENT_ID=spacedf-mpa-client
# Topics to subscribe to (use '+' for wildcards)
MQTT_TOPIC=devices/+/events
 
# --- Authentication ---
MQTT_USERNAME=mpa_user
MQTT_PASSWORD=change_this_to_secure_password

Variable Details

• MQTT_BROKER: The IP or Hostname of the broker.
• MQTT_PORT: 1883 (Plain) or 8883 (Secure).
• MQTT_TOPIC: The data channel to listen to.
• MQTT_USERNAME: Must match a user created in EMQX.
• MQTT_PASSWORD: The password for the user above.

Bootstrap Service

The Bootstrap Service is the main backend API of SpaceDF. It orchestrates the system setup and handles requests from your frontend applications.

1. API URL (HOST)

This variable defines the public address where your Backend API is accessible.

HOST=http://localhost:8000 

HOST=https://api.yourdomain.com

2. Database Password Define the password for the core PostgreSQL database used by the Bootstrap service.

BOOTSTRAP_POSTGRES_PASSWORD="Abcd@1234"

BOOTSTRAP_POSTGRES_PASSWORD="YourStrongUniquePassword"

3. Access Control (CORS)

This setting controls which websites (frontends) are allowed to talk to your backend.

This prevents unauthorized websites from using your API.

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

CORS_ALLOWED_ORIGINS=https://app.yourdomain.com,https://admin.yourdomain.com 

4. Security Key

This key secures the internal operations of the backend.

openssl rand -hex 32

BOOTSTRAP_SECRET_KEY=paste_your_generated_key_here

Organization Initialization

These settings are used to generate the Super Admin account and the Default Organization when SpaceDF runs for the very first time.

1. Setup Credentials

Define your organization name and the login credentials for the owner.

# Replace with your own values.
ORG_NAME="My IoT Company"
OWNER_EMAIL="admin@your-domain.com"
OWNER_PASSWORD="change_this_to_a_secure_password"

2. Variable Details

• ORG_NAME - The display name of your organization (e.g., “SmartHome Solutions”)
• OWNER_EMAIL - The email address used to log in as the System Administrator.
• OWNER_PASSWORD - The master password for the admin account. Must be strong.

🎉 You have now finished configuring the backend services.
Next, continue with the frontend (web app) configuration.

Admin Portal Configuration

The Admin Portal is your central command center. It allows Platform Administrators to manage organizations, users, and system-wide settings.

(Note: This interface is for you and your staff, not for your end-users).

Authentication & URLs

This section secures user sessions and defines the public address of your Admin Portal.

1. Generate Secret Key Create a unique key to encrypt login sessions. Run this command in your terminal:

openssl rand -hex 32

Update the value in your .env file:

# Replace with the generated string
PORTAL_NEXTAUTH_SECRET=your_generated_secret_key

2. Configure Domain Set the URL where administrators will access the portal.

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

HOST_FRONTEND_ADMIN=https://admin.yourdomain.com 
PORTAL_NEXTAUTH_URL=https://admin.yourdomain.com 

Variable Details:

• PORTAL_NEXTAUTH_SECRET: The encryption key for cookies/tokens. Keep this private.
• HOST_FRONTEND_ADMIN: The public URL shown in the browser address bar.
• PORTAL_NEXTAUTH_URL: The base URL used internally by the authentication system for callbacks.

Backend Connection (API)

The Admin Portal needs to communicate with the Backend API to handle user authentication and data retrieval.

Choose your deployment scenario:

# Connects internally via the Docker network
PORTAL_AUTH_API=http://haproxy:3000

# Connects over the public internet
PORTAL_AUTH_API=https://api.yourdomain.com

Variable Details:

• PORTAL_AUTH_API - The endpoint the Admin Portal uses to make server-side requests to the Backend.

Dashboard Configuration

The Dashboard is the primary interface for End Users (your customers). It is used for daily operations, including real-time device monitoring, data visualization, and asset control.

Authentication & URLs

This section secures user sessions and defines the public address of your Dashboard.

1. Generate Secret Key Create a unique key to encrypt login sessions. Run this command in your terminal:

openssl rand -hex 32

Update the value in your .env file:

# Replace with the generated string
DASHBOARD_NEXTAUTH_SECRET=your_generated_secret_key

2. Configure Domain Set the URL where end-users will access the dashboard.

DASHBOARD_NEXTAUTH_URL=http://localhost:3000

DASHBOARD_NEXTAUTH_URL=https://dashboard.yourdomain.com

Variable Details:

• DASHBOARD_NEXTAUTH_SECRET: The encryption key for cookies/tokens. Keep this private.
• DASHBOARD_NEXTAUTH_URL: The public URL (Base URL) used by the authentication system for redirects and callbacks.

Backend Connection (API)

The Dashboard needs to communicate with the Backend API to fetch user data, device status, and charts.

Choose your deployment scenario:

# Connects internally via the Docker network
DASHBOARD_AUTH_API=http://haproxy:3000

# Connects over the public internet
DASHBOARD_AUTH_API=https://api.yourdomain.com

Variable Details:

• DASHBOARD_AUTH_API - The endpoint the Dashboard uses for server-side data fetching and authentication.

Map Services

SpaceDF uses MapTiler to provide map visualization and Reverse Geocoding (converting GPS coordinates into readable addresses like “123 Main St”).

Setup Instructions:

 # Replace with your API Key.
 MAPTILER_API_KEY=__MAPTILER_API_KEY__

MapTiler Documentation 

MQTT (Real-time Data)

The Dashboard connects directly to the MQTT Broker via WebSockets to display real-time charts and device status updates. Without this, the dashboard will not update live.

Configuration by Environment:

# 1. Connection Details
DASHBOARD_MQTT_PROTOCOL=ws
DASHBOARD_MQTT_PORT=8883
DASHBOARD_MQTT_BROKER=emqx.localhost:8000
 
# 2. Public Auth (Read-Only User recommended)
DASHBOARD_MQTT_USERNAME=dashboard_user
DASHBOARD_MQTT_PASSWORD=your_password

# 1. Connection Details
DASHBOARD_MQTT_PROTOCOL=wss
DASHBOARD_MQTT_PORT=443
DASHBOARD_MQTT_BROKER=mqtt.yourdomain.com
 
# 2. Public Auth (Read-Only User recommended)
DASHBOARD_MQTT_USERNAME=dashboard_user
DASHBOARD_MQTT_PASSWORD=your_password

Variable Details:

• DASHBOARD_MQTT_PROTOCOL: ws for local, wss for production (SSL).
• DASHBOARD_MQTT_BROKER: The domain pointing to your MQTT Broker.
• DASHBOARD_MQTT_PORT: The WebSocket port (Default EMQX: 8883 for ws, 8883 for wss).

MQTT over WebSocket 

Starting and Stopping

This section explains how to manage the lifecycle of your SpaceDF instance using standard Docker commands.

Starting the Services

To launch SpaceDF, you will use the provided entrypoint script. This script handles the initialization and orchestrates the Docker containers for you.

Run the following commands in your terminal:

# 1. Grant execution permission (First time only)
chmod +x entrypoint.sh
 
# 2. Start the system
./entrypoint.sh

What happens next?

• The script will trigger Docker to download necessary images and start all services in detached mode (background).
• You can close the terminal window without stopping the application.

Checking service status

After running the startup script, verify that all containers are functioning correctly.

1. Check Status Command Run the following command to list all active services:

docker compose ps

2. Expected Output Give the system about 30-60 seconds to initialize. You should see a list of services where the status column shows Up (healthy).

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

NAME                IMAGE               STATUS                  PORTS
spacedf-backend     spacedf/backend     Up (healthy)            0.0.0.0:8000->8000/tcp
spacedf-dashboard   spacedf/dashboard   Up (healthy)            0.0.0.0:3000->3000/tcp
emqx                emqx/emqx           Up (healthy)            1883/tcp, 8083/tcp...
postgres            postgres:15         Up (healthy)            5432/tcp

Troubleshooting startup issues

If a service shows a status like Exited, Restarting, or remains Created for too long, it means the container failed to start correctly.

1. View Service Logs To identify the specific error, inspect the logs of the problematic service.

# Syntax: docker compose logs -f <service_name>
docker compose logs -f backend

• -f: Follows the log output in real-time (press Ctrl+C to exit).
• Replace backend with the name of the failing service (e.g., dashboard, emqx, postgres)

2. Common Error Patterns When reviewing the logs, look for these common issues:

Stopping the services

To gracefully shut down the SpaceDF platform and release system resources, run the following command:

docker compose down

Data Persistence: Rest assured, this command only removes the containers. Your database, user accounts, and device logs are stored in persistent volumes and will be preserved.

Accessing SpaceDF Services

Once all containers are running successfully, you can access the various components of the SpaceDF platform using the URLs below.

Production URLs
If you have deployed to a live server, replace localhost with your configured domains:

• Dashboard: https://dashboard.yourdomain.com
• Admin Portal: https://admin.yourdomain.com
• API: https://api.yourdomain.com

Updating

SpaceDF frequently releases stable updates to introduce new features, security patches, and performance improvements. To keep your self-hosted instance running smoothly, we recommend keeping it up to date.

Standard Update Procedure

Run the following commands in your terminal to upgrade your deployment.

git pull origin main

docker compose pull 

docker compose up -d

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.

Advanced: Pinning & Rolling Back Versions

In specific scenarios—such as rolling back a buggy update or testing a beta feature—you may need to force a specific version of a service instead of using latest.

Procedure: Update a Single Service

Follow these steps to update (or downgrade) a specific component, for example, the Dashboard.

services:
  dashboard:
    # Change the tag after the colon
    image: ghcr.io/space-df/spacedf-web-app:v2026.01.21

# 1. Pull the specific image
 docker compose pull dashboard
 
# 2. Recreate only this container
 docker compose up -d dashboard

Maintenance Strategy & Resources

Managing updates effectively is key to maintaining a stable IoT platform.

Staying Up to Date: To track the latest features, security patches, and bug fixes, please consult our official channels:

• SpaceDF Release Notes : High-level overview of new features and major changes.
• GitHub Changelog : Detailed technical log of all changes in the self-hosted repository.

Uninstalling

This section guides you through completely removing SpaceDF from your server.

 # The '-v' flag ensures volumes are deleted
 docker compose down -v

# Remove Database files
rm -rf volumes/db/data
 
# Remove File Storage (Uploads/Images)
rm -rf volumes/storage

Verification

At this point, SpaceDF is completely removed.

• Containers: Stopped and deleted.
• Networks: Removed.
• Data: Wiped.

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!