Skip to content

feat: update doc spacedf selfhost #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
huyphan02 wants to merge 2 commits into from
Closed

feat: update doc spacedf selfhost #10

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
77454c2
feat: update doc spacedf selfhost
huyphan02 Jan 21, 2026
ee7e57c
Trigger Build
Quynh-Nguyen Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 93 additions & 119 deletions src/content/getting-started/self-hosted.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ Before installing SpaceDF, ensure you have the following components:
### 1. Clone the Repository

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

### 2. Configure Environment
Expand All @@ -46,154 +46,131 @@ Edit the `.env` file with your configuration:
nano .env
```

### 3. Configure Database Settings
### 3. Configure Environment Variables

Update your database configuration in the `.env` file:
Copy the sections below into your `.env` file. Replace placeholder values (`__...__`) with your real credentials and endpoints.

#### Core Services
```env
# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/spacedf
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=spacedf
DATABASE_USER=spacedf_user
DATABASE_PASSWORD=your_secure_password
```

### 4. Configure Message Broker

Set up RabbitMQ connection details:
# RabbitMQ
RABBITMQ_DEFAULT_USER="default"
RABBITMQ_DEFAULT_PASS="password"

```env
# RabbitMQ Configuration
RABBITMQ_URL=amqp://username:password@localhost:5672/
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=spacedf_rabbit
RABBITMQ_PASSWORD=your_rabbit_password
# Redis
REDIS_HOST="redis://redis:6379/1"
```

### 5. Configure Redis Cache

Add Redis configuration:

#### Authentication & Identity
```env
# Redis Configuration
REDIS_URL=redis://localhost:6379/0
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# 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__"
```

### 6. Start Services

Launch all SpaceDF services using Docker Compose:

```bash
docker-compose up -d
```

This command will:
- Start all required containers
- Set up networking between services
- Initialize persistent volumes

### 7. Initialize Database

Run database migrations and create the initial organization:

```bash
# Run schema migrations
docker-compose exec backend python manage.py migrate_schemas

# Create your first organization
docker-compose exec backend python manage.py create_organization
```

## Configuration Options

### Essential Configuration

Key settings you must configure in your `.env` file:

#### Application Settings
#### Storage & Email
```env
# Basic Application Configuration
SECRET_KEY=your_very_secure_secret_key_here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
# 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"
```

#### Authentication Providers
#### Service Credentials
```env
# Social Authentication (Optional)
GOOGLE_OAUTH2_KEY=your_google_oauth_key
GOOGLE_OAUTH2_SECRET=your_google_oauth_secret

GITHUB_KEY=your_github_oauth_key
GITHUB_SECRET=your_github_oauth_secret
# 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__"
```

#### External Service Integrations
#### Messaging & MQTT
```env
# Email Configuration
EMAIL_HOST=smtp.yourmailprovider.com
EMAIL_PORT=587
EMAIL_HOST_USER=your_email_user
EMAIL_HOST_PASSWORD=your_email_password
EMAIL_USE_TLS=True

# Storage Configuration
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_STORAGE_BUCKET_NAME=your_s3_bucket_name
AWS_S3_REGION_NAME=us-east-1
# 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"
```

### Security Configuration

<Callout type="error">
**Security Important**: Always use strong passwords, enable SSL/TLS, and configure proper firewall rules for production deployments.
</Callout>

#### SSL/TLS Setup
#### Organization Bootstrapping
```env
# SSL Configuration
USE_TLS=True
SECURE_SSL_REDIRECT=True
SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https
ORG_NAME="Default Organization"
ORG_SLUG="default-org"
OWNER_EMAIL="admin@example.com"
OWNER_PASSWORD="changeme123#Test"
```

## Post-Installation Setup

### 1. Create Admin User

Create your first administrator account:

```bash
docker-compose exec backend python manage.py createsuperuser
#### Frontend / NextAuth
```env
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"
```

### 2. Configure Domain and SSL
### Start Services

Update your domain configuration and set up SSL certificates:
Launch all SpaceDF services via Docker Compose using shell script:

```bash
# Update ALLOWED_HOSTS in .env file
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

# Restart services to apply changes
docker-compose restart
./entrypoint.sh
```

### 3. Test Installation
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
Expand All @@ -217,9 +194,6 @@ docker-compose pull
# Restart services
docker-compose down
docker-compose up -d

# Run any new migrations
docker-compose exec backend python manage.py migrate_schemas
```

## Troubleshooting
Expand Down