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:

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

Maintenance and Updates

Regular Maintenance Tasks

Database Backups: Set up automated PostgreSQL backups
Log Rotation: Configure log file rotation to prevent disk space issues
Security Updates: Regularly update Docker images and system packages
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:

API Configuration - Set up API access and authentication
Deployment Guide - Production deployment best practices
Device Management - Add and configure your IoT devices
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.