feat: update doc spacedf selfhost

[huyphan02]

Self-Hosted Installation

Deploy SpaceDF on your own infrastructure for complete control and customization. This guide will walk you through setting up SpaceDF using Docker and configuring all required services.

Prerequisites

Before installing SpaceDF, ensure you have the following components:

Required Software

• Docker (version 20.0 or higher)
• Docker Compose (version 2.0 or higher)
• Git for repository cloning

Required Services

• PostgreSQL (version 13 or higher) - Main database
• RabbitMQ (version 3.8 or higher) - Message broker
• Redis (version 6.0 or higher) - Cache and session storage

System Requirements

• RAM: Minimum 4GB (8GB recommended)
• Storage: At least 20GB available space
• Network: Open ports 80, 443, and any custom ports for your setup

Installation Steps

1. Clone the Repository

git clone https://github.com/Space-DF/spacedf-core.git
cd spacedf-core

2. Configure Environment

Copy the example environment file and customize it for your setup:

cp .env.example .env

Edit the .env file with your configuration:

nano .env

3. Configure Environment Variables

Copy the sections below into your .env file. Replace placeholder values (__...__) with your real credentials and endpoints.

Core Services

# RabbitMQ
RABBITMQ_DEFAULT_USER="default"
RABBITMQ_DEFAULT_PASS="password"

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

Authentication & Identity

# JWT
JWT_PRIVATE_KEY="__JWT_PRIVATE_KEY__"
JWT_PUBLIC_KEY="__JWT_PUBLIC_KEY__"

# Auth Service
AUTH_POSTGRES_PASSWORD="__AUTH_POSTGRES_PASSWORD__"
AUTH_SECRET_KEY="__AUTH_SECRET_KEY__"
DEFAULT_TENANT_HOST="localhost"
ROOT_API_KEY="__ROOT_API_KEY__"

Storage & Email

# S3
AWS_ACCESS_KEY_ID="__AWS_ACCESS_KEY_ID__"
AWS_SECRET_ACCESS_KEY="__AWS_SECRET_ACCESS_KEY__"
AWS_STORAGE_BUCKET_NAME="spacedf-s3-1f841081-c8e98ef7bb21"
AWS_REGION="__AWS_REGION__"

# AWS SES / Email
EMAIL_BACKEND="__EMAIL_BACKEND__"
EMQX_HOST="__EMQX_HOST__"
EMAIL_PORT="__EMAIL_PORT__"
EMAIL_USE_TLS="__EMAIL_USE_TLS__"
EMAIL_HOST_USER="__EMAIL_HOST_USER__"
EMAIL_HOST_PASSWORD="__EMAIL_HOST_PASSWORD__"
DEFAULT_FROM_EMAIL="no-reply@gmail.com"

Service Credentials

# Dashboard Service
DASHBOARD_POSTGRES_PASSWORD="postgres"
DASHBOARD_SECRET_KEY="__DASHBOARD_SECRET_KEY__"

# Device Service
DEVICE_POSTGRES_PASSWORD="postgres"
DEVICE_SECRET_KEY="__DEVICE_SECRET_KEY__"
TELEMETRY_SERVICE_URL="http://telemetry:8080"

# Bootstrap Service
HOST="http://localhost:8000"
BOOTSTRAP_POSTGRES_PASSWORD="postgres"
CORS_ALLOWED_ORIGINS="http://localhost,http://localhost:3000"
BOOTSTRAP_SECRET_KEY="__BOOTSTRAP_SECRET_KEY__"

Messaging & MQTT

# EMQX Service
EMQX_USERNAME="user"
EMQX_PASSWORD="password123"

# Broker Bridge Service
MQTT_BROKER_BRIDGE_USERNAME="BrokerBridgeService"
MQTT_BROKER_BRIDGE_PASSWORD="Default@1234"
MQTT_TOPICS="tenant/+/transformed/device/location"

# MPA Service
MQTT_BROKER="emqx"
MQTT_USERNAME="MPAService"
MQTT_PASSWORD="Default@1234"
MQTT_PORT="1883"
MQTT_CLIENT_ID="mpa-service-mqtt-bridge"
MQTT_TOPIC="tenant/{tenant}/device/data"

Organization Bootstrapping

ORG_NAME="Default Organization"
ORG_SLUG="default-org"
OWNER_EMAIL="admin@example.com"
OWNER_PASSWORD="changeme123#Test"

Frontend / NextAuth

PORTAL_NEXTAUTH_SECRET="__PORTAL_NEXTAUTH_SECRET__"
HOST_FRONTEND_ADMIN="http://localhost:3001"
DASHBOARD_NEXTAUTH_SECRET="__DASHBOARD_NEXTAUTH_SECRET__"
SPACE_API_KEY="__SPACE_API_KEY__"
MAPTILER_API_KEY="__MAPTILER_API_KEY__"
DASHBOARD_MQTT_USERNAME="anonymous"
DASHBOARD_MQTT_PASSWORD="password123"
DASHBOARD_MQTT_PROTOCOL="ws"
DASHBOARD_MQTT_PORT="8883"
DASHBOARD_MQTT_BROKER="emqx.spacedf.net"
HOST_FRONTEND="http://localhost:3000"

Start Services

Launch all SpaceDF services via Docker Compose using shell script:

./entrypoint.sh

This command will:

• Start all required containers
• Set up networking between services
• Initialize persistent volumes

Test Installation

Verify your installation by:

1. Accessing the web interface at your configured domain
2. Logging in with your admin credentials
3. Creating a test organization
4. Checking all services are running: docker-compose ps

Maintenance and Updates

Regular Maintenance Tasks

1. Database Backups: Set up automated PostgreSQL backups
2. Log Rotation: Configure log file rotation to prevent disk space issues
3. Security Updates: Regularly update Docker images and system packages
4. Monitoring: Implement monitoring for system resources and application health

Updating SpaceDF

To update to the latest version:

# Pull latest changes
git pull origin main

# Update Docker images
docker-compose pull

# Restart services
docker-compose down
docker-compose up -d

Troubleshooting

Common Issues

Services not starting:

• Check Docker logs: docker-compose logs [service-name]
• Verify port availability
• Ensure sufficient disk space and memory

Database connection errors:

• Verify PostgreSQL is running
• Check connection credentials in .env
• Ensure database exists and user has proper permissions

Performance issues:

• Monitor system resources
• Check database query performance
• Review Redis cache hit rates

Next Steps

After successful installation:

1. API Configuration - Set up API access and authentication
2. Deployment Guide - Production deployment best practices
3. Device Management - Add and configure your IoT devices
4. Organization Setup - Configure multi-tenancy and user management

Need Help?

• Community Forum - Get help from the community
• Discord Server - Real-time support from developers
• GitHub Issues - Report bugs or request features
• Professional Support - Enterprise installation assistance

---

Need professional installation assistance? Our team offers professional installation services with custom configuration and ongoing support.

[vercel]

@huyphan02 must be a member of the DF team on Vercel to deploy.
- Click here to add @huyphan02 to the team.
- If you initiated this build, request access.

Learn more about collaboration on Vercel and other options here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
spacedf-docs	Ready	Preview, Comment	Jan 21, 2026 4:29am