diff --git a/public/screenshots/bucket-guide.png b/public/screenshots/bucket-guide.png new file mode 100644 index 0000000..2dcfa57 Binary files /dev/null and b/public/screenshots/bucket-guide.png differ diff --git a/public/screenshots/iam-credentials.png b/public/screenshots/iam-credentials.png new file mode 100644 index 0000000..1b4e85c Binary files /dev/null and b/public/screenshots/iam-credentials.png differ diff --git a/src/app/_components/GettingStartedCards.jsx b/src/app/_components/GettingStartedCards.jsx index d32b456..63b6a23 100644 --- a/src/app/_components/GettingStartedCards.jsx +++ b/src/app/_components/GettingStartedCards.jsx @@ -1,6 +1,6 @@ -"use client"; +"use client" -import Link from "next/link"; +import Link from "next/link" const cards = [ { @@ -29,7 +29,7 @@ const cards = [ title: "Self-Hosted Installation", description: "Deploy SpaceDF on your own infrastructure for complete control and customization.", - href: "/docs/getting-started/self-hosted", + href: "/docs/getting-started/self-hosting", image: "https://d33et8skld5wvq.cloudfront.net/images/spacedf-docs/self-host.png", icon: ( @@ -47,12 +47,12 @@ const cards = [ ), }, -]; +] export function GettingStartedCards() { return (
- {cards.map(card => ( + {cards.map((card) => (
{card.title} @@ -221,5 +221,5 @@ export function GettingStartedCards() { } `}
- ); + ) } diff --git a/src/app/blog/v2025.12.19/page.mdx b/src/app/blog/v2025.12.19/page.mdx index b3daab4..4136fbd 100644 --- a/src/app/blog/v2025.12.19/page.mdx +++ b/src/app/blog/v2025.12.19/page.mdx @@ -52,7 +52,7 @@ The platform is built with a microservices architecture: To get started with SpaceDF: 1. Visit our [Getting Started guide](/getting-started) -2. Set up your [Cloud deployment](/getting-started/cloud-setup) or [Self-hosted installation](/getting-started/self-hosted) +2. Set up your [Cloud deployment](/getting-started/cloud-setup) or [Self-hosted installation](/getting-started/self-hosting) 3. Follow the [Onboarding guide](/onboarding) ## Support diff --git a/src/content/getting-started/index.mdx b/src/content/getting-started/index.mdx index 496ebd8..4b29a07 100644 --- a/src/content/getting-started/index.mdx +++ b/src/content/getting-started/index.mdx @@ -3,7 +3,7 @@ asIndexPage: true sidebarTitle: Installation --- -import {Cards, Callout} from "nextra/components"; +import { Cards, Callout } from "nextra/components"; # Getting Started with SpaceDF @@ -41,7 +41,7 @@ Ready to dive in? The getting started guides take you step-by-step through Space /> } title="Self-Hosted Installation" - href="/docs/getting-started/self-hosted" + href="/docs/getting-started/self-hosting" /> diff --git a/src/content/getting-started/self-hosting/docker/_meta.js b/src/content/getting-started/self-hosting/docker/_meta.js new file mode 100644 index 0000000..57dff1e --- /dev/null +++ b/src/content/getting-started/self-hosting/docker/_meta.js @@ -0,0 +1,4 @@ +export default { + "quick-start": "Quick Start", + "advanced-setup": "Advanced Setup", +} diff --git a/src/content/getting-started/self-hosting/docker.mdx b/src/content/getting-started/self-hosting/docker/advanced-setup.mdx similarity index 78% rename from src/content/getting-started/self-hosting/docker.mdx rename to src/content/getting-started/self-hosting/docker/advanced-setup.mdx index 3917fd6..3ef333d 100644 --- a/src/content/getting-started/self-hosting/docker.mdx +++ b/src/content/getting-started/self-hosting/docker/advanced-setup.mdx @@ -8,32 +8,40 @@ import { } from "@/app/_components/NumberOfContent.jsx" -# Self-Hosting with Docker +# Advanced Setup with Docker -> Learn how to configure and deploy SpaceDF Platform with Docker. +> This guide covers **detailed configuration**, **customization**, **and operational topics** for running SpaceDF with Docker Compose. ---- +
+

Use this guide if you need:

+ +
+If you only want to get SpaceDF running quickly with default settings, see [Quick Start](/docs/getting-started/self-hosting/docker/quick-start). -Docker is the easiest way to start self-hosting SpaceDF. -You can usually get everything running in under 30 minutes. +--- ## Contents
- - - - - - - - + + + + + + + + -## Before you begin +## 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 +- [Basic Linux](https://www.digitalocean.com/community/tutorials/linux-commands) server usage (connecting to a server, running commands). +- How Docker and Docker Compose work at a high level. +- Basic networking concepts such as [ports](https://www.cloudflare.com/learning/network-layer/what-is-a-computer-port) and [firewalls](https://www.cloudflare.com/learning/security/what-is-a-firewall/) Make sure the following tools are installed on your machine or server: - [Git](https://git-scm.com/downloads) – used to download the SpaceDF source code @@ -94,25 +102,19 @@ Minimum requirements for running all SpaceDF Platform components, suitable for d Follow the steps below to install and run SpaceDF on your machine. ```bash copy -# 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 +# Get the code +cd spacedf-project +git clone https://github.com/Space-DF/spacedf-core.git # Switch to your project directory -cd spacedf-project +cd spacedf-core + +# Copy the env vars +cp .env.example .env # Pull the latest images docker compose pull @@ -127,17 +129,6 @@ You must replace these values before starting SpaceDF in a self-hosted environme Review the configuration options below and make sure all secret values are set before starting SpaceDF. -### Quick setup (experimental) -To generate and apply all secrets at once you can run: - -```sh copy -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. @@ -149,18 +140,24 @@ These environment variables configure the backend services that power the self-h 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 is used by SpaceDF for **background tasks** and **internal message** processing between services. + +You can **choose any username and password you want**, as long as: +- The same values are used by **RabbitMQ** and **all SpaceDF services** +- The credentials are defined in the environment variables below ```bash copy -RABBITMQ_DEFAULT_USER=default -RABBITMQ_DEFAULT_PASS=password +# Replace with your own values. +RABBITMQ_DEFAULT_USER=your_username +RABBITMQ_DEFAULT_PASS=your_password ``` - `RABBITMQ_DEFAULT_USER` - The username SpaceDF uses to connect to RabbitMQ. - `RABBITMQ_DEFAULT_PASS` - The password for the RabbitMQ user above. - Do not use simple or common passwords. This account controls access to your message queue. + Do not use simple or common passwords. This account controls access to your message queue.
+ Keep these credentials safe—you may need them to log in to RabbitMQ for troubleshooting later. ##### Authentication (JWT) @@ -198,16 +195,6 @@ JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----... > 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. -```bash copy -# 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** @@ -223,23 +210,34 @@ GOOGLE_CLIENT_SECRET=your_google_client_secret Go to **APIs & Services → Credentials**. - Create an **OAuth 2.0 Client ID:** -
    -
  • - Application type: **Web application** -
    • -
  • - Authorized redirect URI: - ```string copy - https://your-domain.com/auth/google/callback - ``` -
    • -
+ Create an **OAuth 2.0 Client ID:**
+ Application type: **Web application**
+ + + Authorized redirect URI: (`GOOGLE_CALLBACK_URL`)
+ This is the callback URL that Google redirects to after a user successfully signs in with Google. + ```bash copy + # Production + https://your-domain.com/auth/google/callback + + # Development + http://localhost:3000/auth/google/callback + ``` - + Copy the generated **Client ID** and **Client Secret** into your `.env` file. +```bash copy +# Replace with your own values. +GOOGLE_CALLBACK_URL=https://spacedf.example.com/auth/google/callback +GOOGLE_CLIENT_ID=1234567890-abcxyz.apps.googleusercontent.com #(Step 5) +GOOGLE_CLIENT_SECRET=your_google_client_secret #(Step 5) +``` +- `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.***) + **Security notes** - Do not commit `GOOGLE_CLIENT_SECRET` to Git @@ -305,44 +303,71 @@ 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**. +> The Amazon S3 service is used by SpaceDF to store files such as uploads, assets, and generated data. + + + SpaceDF supports **Amazon S3 only** for file storage in this setup. + + +**How it works** + +SpaceDF connects to Amazon S3 using **IAM credentials** that you provide in the `.env` file. All file operations (upload, read, delete) are handled internally by SpaceDF services.
+End users do **not** need AWS accounts or credentials. **How to configure** +If you do not already have an AWS account, create one at, [see more](https://repost.aws/knowledge-center/create-and-activate-aws-account):
+https://signin.aws.amazon.com/signup?request_type=register + +After creating your account, sign in to the AWS Management Console to continue with the steps below. + +***Create an S3 bucket*** + - **Create an S3 bucket** -
    -
  • - Create a bucket in your AWS account -
    • -
  • - Note the **bucket name** and **region** -
    • -
+ Open the [Amazon S3 Console](https://console.aws.amazon.com/s3/) - - **Create IAM credentials** -
    -
  • - Create an IAM user with access to the bucket -
    • -
  • - Generate an **Access Key ID** and **Secret Access Key** -
    • -
+ Create a new bucket + + + Choose:
+ A unique bucket name -> will be used for `AWS_STORAGE_BUCKET_NAME`
+ An AWS region close to your server → will be used for `AWS_REGION` + +Save the bucket name and region for later use. + +Read more: [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket) + +***Create IAM credentials*** + + Open the [AWS IAM Console](https://console.aws.amazon.com/iam/) + + + Create a new **IAM user** + - Set values in `.env` - ```bash copy + Grant the user access to the S3 bucket
+ *Recommended:* grant only required S3 permissions (read/write) + + + Create an **Access Key** for the user
+ Access Key ID, Secret Access Key + + + +Read more: [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) + +***Set values in `.env`*** +```bash copy # 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***) @@ -356,12 +381,6 @@ DEFAULT_TENANT_HOST=app.spacedf.example - Rotate access keys if they are exposed -**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 - ##### Redis > Redis is used by SpaceDF for caching and fast data access. @@ -446,28 +465,27 @@ 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 -```bash copy -# Replace with your own values. -TELEMETRY_SERVICE_URL=http://telemetry-service:8080 -``` - -Example: External telemetry service -```bash copy -# Replace with your own values. -TELEMETRY_SERVICE_URL=https://telemetry.spacedf.example -``` - **Security notes** - Do not commit passwords or secret keys to Git - - Use HTTPS for external telemetry services in production - Rotate secrets if they are exposed +**Telemetry service URL** + +Defines the internal Docker service address that SpaceDF uses to communicate with the Telemetry Service. + +When using the **default Docker setup**, the Telemetry Service runs as a Docker container and is accessible via its **service name**. + +```bash copy +# Default (recommended) +TELEMETRY_SERVICE_URL=http://telemetry-service:8080 +``` +- This value is the same for both **local and production** deployments when using Docker Compose. +- The Telemetry Service runs from a **Docker image** and is exposed internally. +- You **do not need to change this value** in most cases. + +Only change this value if you modify the Telemetry Service name or port in `docker-compose.yml`. ##### EMQX Service > EMQX is the MQTT broker used by SpaceDF to handle device messaging and real-time communication. @@ -508,7 +526,7 @@ MQTT_BROKER_BRIDGE_PASSWORD=change_this_to_a_secure_password Specify one or more topics, separated by commas. ```bash copy # Replace with your own values. -MQTT_TOPICS=devices/+/telemetry,devices/+/status +MQTT_TOPICS=device/+/telemetry,device/+/status ``` `MQTT_TOPICS` - A list of MQTT topics that SpaceDF subscribes to or bridges. @@ -525,26 +543,6 @@ MQTT_TOPICS=devices/+/telemetry,devices/+/status 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. - -```bash copy -# 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** Sign in to the [AWS Console](https://aws.amazon.com/console/) @@ -578,6 +576,25 @@ DEFAULT_FROM_EMAIL=no-reply@spacedf.example Find your SMTP endpoint and set it as `EMAIL_HOST`. +Set the following values in your `.env` file. +```bash copy +# 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. + ##### MPA Service > The MPA Service connects SpaceDF to an MQTT broker to receive and publish messages for application-level processing. @@ -606,23 +623,29 @@ MQTT_TOPIC=devices/+/events ##### Bootstrap Service -> The Bootstrap Service is responsible for initial system setup and cross-service coordination when SpaceDF starts. +> The Bootstrap Service is the **backend service** responsible for initial system setup and cross-service coordination when SpaceDF starts. + +This service runs inside Docker as the SpaceDF backend. **Service host** -Set this to the URL where the Bootstrap Service is reachable. +This value defines the **base URL** where the Bootstrap (Backend) service is accessible. ```bash copy -# Replace with your own values. +# Local development (default) HOST=http://localhost:8000 ``` -For production, use your public domain: +For production deployments, set this to your **public API domain**: ```bash copy -# Replace with your own values. +# Replace with your public API domain. 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. +If you change the backend port, make sure to update: +- HOST in your `.env` file +- The backend port in `docker-compose.yml` + **CORS origins** List all frontend origins that should be allowed to access the service. @@ -630,6 +653,7 @@ Separate multiple values with commas. Development (local) ```bash copy +# Local development (default) CORS_ALLOWED_ORIGINS=http://localhost,http://localhost:3000,http://localhost:3001 ``` @@ -903,13 +927,42 @@ 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. -| Service | Port | -| ---------------- | ----- | -| Dashboard | 3000 | -| Admin Portal | 3001 | -| Backend API | 8000 | -| EMQX (API) | 18083 | -| MQTT (WebSocket) | 8883 | +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Service + + Port +
Dashboardlocalhost:3000
Admin Portallocalhost:3001
Backend APIlocalhost:8000
EMQX (API)localhost:18083
MQTT (WebSocket)localhost:8883
+
**Notes** diff --git a/src/content/getting-started/self-hosting/docker/index.mdx b/src/content/getting-started/self-hosting/docker/index.mdx new file mode 100644 index 0000000..f6080bd --- /dev/null +++ b/src/content/getting-started/self-hosting/docker/index.mdx @@ -0,0 +1,48 @@ +--- +asIndexPage: true +sidebarTitle: Docker +--- + +import { RichCardOptions, RichCardOption } from "@/app/_components/RichCard.jsx" + +# Self-Hosting with Docker +> This section helps you run SpaceDF on your own infrastructure using **Docker** and **Docker Compose**. + +Choose the setup path that best fits your needs: + + + + 🚀 +
+ } + title="Quick Start" + badge="Recommended" + description="Get SpaceDF running quickly using Docker Compose with default settings." + href="/docs/getting-started/self-hosting/docker/quick-start" + /> + + + ⚙️ + + } + title="Advanced Setup" + description="Full Docker Compose configuration, security settings, and production guidance." + href="/docs/getting-started/self-hosting/docker/advanced-setup" + /> + +--- +## Prerequisites + +- [Basic Linux](https://www.digitalocean.com/community/tutorials/linux-commands) server usage (connecting to a server, running commands). +- How Docker and Docker Compose work at a high level. +- Basic networking concepts such as [ports](https://www.cloudflare.com/learning/network-layer/what-is-a-computer-port) and [firewalls](https://www.cloudflare.com/learning/security/what-is-a-firewall/) + +If you are unsure which path to choose, start with **Quick Start**. You can move to **Advanced Setup** at any time. diff --git a/src/content/getting-started/self-hosting/docker/quick-start.mdx b/src/content/getting-started/self-hosting/docker/quick-start.mdx new file mode 100644 index 0000000..5faa8ce --- /dev/null +++ b/src/content/getting-started/self-hosting/docker/quick-start.mdx @@ -0,0 +1,113 @@ +--- +sidebarTitle: Quick Start +--- + +import { Steps } from 'nextra/components' + +# Quick Start + +> This guide helps you get **SpaceDF running quickly** on your own infrastructure using **Docker Compose** and **default settings**. + +
+

Before You Begin

+ + If you are unsure about any of the requirements above, see [Prerequisites](/docs/getting-started/self-hosting/docker/advanced-setup#prerequisites) for details. +
+ +If you need advanced configuration, security tuning, or production setup, see [Advanced Setup](/docs/getting-started/self-hosting/docker/advanced-setup) instead. + + +### Get the Source Code + +```bash copy +# Make your new spacedf project directory +mkdir spacedf-project + +# Clone the SpaceDF repository: +cd spacedf-project +git clone https://github.com/Space-DF/spacedf-core.git + +# Switch to your project directory +cd spacedf-core + +# Copy the env vars +cp .env.example .env +``` + +### Configure Environment Variables +To generate and apply all secrets at once you can run: +```sh copy +chmod +x generate-keys.sh +./generate-keys.sh +``` +The default values are sufficient for Quick Start. + +### Pull Images and Start SpaceDF +From the directory that contains your `./entrypoint.sh` file, run: + +```bash copy +# Start all services in the background +chmod +x entrypoint.sh +./entrypoint.sh +``` +This script pulls the required Docker images and starts all SpaceDF services in the background. + +### Verify Services +Confirm that all containers are running: +```bash copy +docker compose ps +``` +When all services are healthy, SpaceDF is ready to use. + + +### Default Ports +After startup, SpaceDF services are available on the following default ports: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Service + + Port +
Dashboardlocalhost:3000
Admin Portallocalhost:3001
Backend APIlocalhost:8000
EMQX (API)localhost:18083
MQTT (WebSocket)localhost:8883
+
+Make sure these ports are open on your server and not used by other services. + +🎉 **You’re all set!** SpaceDF is now running on your server. Enjoy building with it. + +--- + +Continue with [Advanced Setup](/docs/getting-started/self-hosting/docker/advanced-setup) to customize your deployment.