diff --git a/public/screenshots/google-oauth.png b/public/screenshots/google-oauth.png new file mode 100644 index 0000000..17d0f89 Binary files /dev/null and b/public/screenshots/google-oauth.png differ diff --git a/src/app/_components/CardInfo.jsx b/src/app/_components/CardInfo.jsx index 12b2fbd..2723a87 100644 --- a/src/app/_components/CardInfo.jsx +++ b/src/app/_components/CardInfo.jsx @@ -9,7 +9,7 @@ export const CardInfo = ({ }) => { return (
{title && (

{title}

diff --git a/src/app/_components/NumberOfContent.jsx b/src/app/_components/NumberOfContent.jsx index 98da1bd..69a03c0 100644 --- a/src/app/_components/NumberOfContent.jsx +++ b/src/app/_components/NumberOfContent.jsx @@ -10,7 +10,7 @@ export const NumberOfContent = ({ }) => { return (
-
+
{number}
@@ -37,7 +37,7 @@ export const NumberOfContent = ({ export const NumberWithMdx = ({ number, children, className }) => { return (
-
+
{number}
diff --git a/src/components/ui/badge.tsx b/src/components/ui/badge.tsx new file mode 100644 index 0000000..ba40cc1 --- /dev/null +++ b/src/components/ui/badge.tsx @@ -0,0 +1,48 @@ +import * as React from "react" +import { Slot } from "@radix-ui/react-slot" +import { cva, type VariantProps } from "class-variance-authority" + +import { cn } from "@/lib/utils" + +const badgeVariants = cva( + "inline-flex items-center justify-center rounded-full border border-transparent px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden", + { + variants: { + variant: { + default: "bg-primary text-primary-foreground [a&]:hover:bg-primary/90", + secondary: + "bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90", + destructive: + "bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60", + outline: + "border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground", + ghost: "[a&]:hover:bg-accent [a&]:hover:text-accent-foreground", + link: "text-primary underline-offset-4 [a&]:hover:underline", + }, + }, + defaultVariants: { + variant: "default", + }, + } +) + +function Badge({ + className, + variant = "default", + asChild = false, + ...props +}: React.ComponentProps<"span"> & + VariantProps & { asChild?: boolean }) { + const Comp = asChild ? Slot : "span" + + return ( + + ) +} + +export { Badge, badgeVariants } diff --git a/src/content/getting-started/self-hosting/docker/advanced-setup.mdx b/src/content/getting-started/self-hosting/docker/advanced-setup.mdx index 1c5f903..84cf060 100644 --- a/src/content/getting-started/self-hosting/docker/advanced-setup.mdx +++ b/src/content/getting-started/self-hosting/docker/advanced-setup.mdx @@ -2,6 +2,8 @@ import { Steps } from "nextra/components" import { Table } from 'nextra/components' import { Callout } from 'nextra/components' import { CardInfo } from "@/app/_components/CardInfo.jsx" +import { Tabs } from 'nextra/components' +import { Badge } from "@/components/ui/badge.tsx" import { NumberOfContent, @@ -29,7 +31,7 @@ If you only want to get SpaceDF running quickly with default settings, see [Quic - + @@ -118,108 +120,256 @@ cp .env.example .env docker compose pull ``` -## Configuring and securing SpaceDF +## Configuration & Security -The `.env.example` file includes sample passwords and keys for reference only. -You must replace these values before starting SpaceDF in a self-hosted environment. +Before starting SpaceDF, you need to set up the environment variables. - - Review the configuration options below and make sure all secret values are set before starting SpaceDF. - + + + + Copy the `.env.example` file in the root directory. + + + Rename the copy to `.env` + + + Update the values in `.env` following the guide below. + + - -***Security notes*** -- **Do not commit** passwords, secrets, or API keys to Git -- **Do not expose secret values** on the client side (browser) -- If a value is marked as **“Keep this value secret”**, it must never be shared publicly -- **Do not reuse secrets** across systems or environments -- Use strong and unique passwords for all services -- Use the **minimum required permissions** for all credentials -- **Rotate keys immediately** if they are **exposed** -- Use **HTTPS / WSS** in production environments - + + Run the following command in your project root directory: + + ```bash copy + # Switch to your project directory + cd spacedf-core + + # Copy the env vars + cp .env.example .env + ``` + + + + + ⚠️ **Action Required:** You must replace all sample values in the .env file before starting the app. + + + + - **Use strong passwords**: Make them long and unique for every service. + - **Use HTTPS**: Always use a secure connection (https://) when your site is live. + - **Keep it private**: If a value says "Secret", never share it with anyone. + + + + - **Do not share your `.env` file**: Never upload this file to GitHub, GitLab, or share screenshots of it. + - **Do not reuse passwords**: Don't use the same password you use for other websites. + - **Do not expose secrets**: Never use these secret keys in your frontend code (browser-side). + ### Configuring Environment Variables -This section explains how to configure the required environment variables in the `.env` file before starting SpaceDF. +Now that you have your `.env` file, you need to configure the settings. -Open the `.env` file using a text editor (for example: VS Code, Nano, or Notepad). + + Open the file Open the `.env` file using any text editor of your choice.
-#### Services Configuration + Recommended Editors: + - **All platforms:** VS Code (Recommended for easier reading) + - **Windows:** Notepad + - **macOS:** TextEdit + - **Linux:** Nano or Vim + + + **Update the values** Review the sections below and update the corresponding values in your file. + -These environment variables configure the backend services that power the self-hosted SpaceDF server. -Backend services include APIs, messaging, databases, and integrations required to run the core system. + + - Required These values are mandatory. SpaceDF **will not start** without them. + - Optional These are for advanced features. You can leave them as default or skip them for now + - Coming Soon Features planned for future updates. **No action required** at this time. + + +#### Backend Services -##### RabbitMQ credentials -> RabbitMQ is used by SpaceDF for **background tasks** and **internal message** processing between services. +This section configures the connections between SpaceDF and your infrastructure (such as your database and cache). -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 +These settings are the backbone of your server. + +##### RabbitMQ Configuration +Required + +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. ```bash copy -# Replace with your own values. -RABBITMQ_DEFAULT_USER=your_username -RABBITMQ_DEFAULT_PASS=your_password +RABBITMQ_DEFAULT_USER="your_secure_username" +RABBITMQ_DEFAULT_PASS="your_secure_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.
- Keep these credentials safe—you may need them to log in to RabbitMQ for troubleshooting later. - +**Variable Details:** +- `RABBITMQ_DEFAULT_USER`: The username for the connection. +- `RABBITMQ_DEFAULT_PASS`: The password for the connection. + + - **Consistency:** If you are running RabbitMQ via Docker or another service, these values must match the credentials defined there. + - **Security:** Use a strong password. You may need these credentials later to log in to the RabbitMQ dashboard for troubleshooting + --- ##### Authentication (JWT) -> SpaceDF uses JSON Web Tokens (JWT) to authenticate users and secure API requests. +Required -You must set a **private key** and a **public key** before starting SpaceDF. +SpaceDF uses **JSON Web Tokens (JWT)** to secure API requests. You need to generate a specific key pair for this to work. - **Recommended:** Generate a new key pair + **Generate & Copy Keys**
+ Choose your operating system below to generate and copy the keys. + + + + **1. Generate Keys** + Open Terminal and run: + ```bash copy + openssl genrsa -out private_key.pem 2048 + openssl rsa -in private_key.pem -pubout -out public_key.pem + ``` + + **2. Copy to Clipboard** + Run these commands to copy the keys directly (no manual selection needed): + ```bash copy + # Copy Private Key + pbcopy < private_key.pem + + # Copy Public Key + pbcopy < public_key.pem + ``` + + + + > **Note:** Please use **Git Bash** for these commands. Do not use PowerShell or CMD. + + **1. Generate Keys** + Run this in Git Bash: + ```bash copy + openssl genrsa -out private_key.pem 2048 + openssl rsa -in private_key.pem -pubout -out public_key.pem + ``` + + **2. Copy to Clipboard** + Run these commands to copy the keys to your Windows clipboard: + ```bash copy + # Copy Private Key + cat private_key.pem | clip + + # Copy Public Key + cat public_key.pem | clip + ``` + + + + **1. Generate Keys** + Open Terminal and run: + ```bash copy + openssl genrsa -out private_key.pem 2048 + openssl rsa -in private_key.pem -pubout -out public_key.pem + ``` + + **2. Copy Content** + Run these commands to view the key content, then manually select and copy it: + ```bash copy + # Show Private Key -> Copy the output + cat private_key.pem + + # Show Public Key -> Copy the output + cat public_key.pem + ``` + + -```bash copy -openssl genrsa -out private_key.pem 2048 -openssl rsa -in private_key.pem -pubout -out public_key.pem -``` + - Copy the contents of each file into your `.env` file: + **Update `.env` file**
+ Paste the copied keys into your `.env` file. -```bash copy -JWT_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----... -JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----... -``` -- `JWT_PRIVATE_KEY` - Signs authentication tokens (***Keep this key secret.***). -- `JWT_PUBLIC_KEY` - Verifies authentication tokens. This key can be shared with other services if needed. -> Make sure the keys are pasted correctly and not broken across lines. + + ⚠️ **Formatting Rule:** Because these keys span multiple lines, you **must** enclose the entire value in double quotes (`""`). If you omit the quotes, the server will fail to start. + + +**Example of correct formatting:** + +```bash +# ✅ 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 -> Google OAuth allows users to sign in to SpaceDF using their Google account. +Optional -To enable Google login, you need to create OAuth credentials in the ***Google Cloud Console*** and set the values below in your `.env` file. +Enable this to allow users to sign in to SpaceDF using their Google accounts. -**How to get Google OAuth credentials** - - Go to the [Google Cloud Console](https://console.cloud.google.com/) +You will need to generate credentials in the `Google Cloud Console`. + +**1. Get Credentials** + +Follow these steps to create your `Client ID` and `Secret`. + + + Go to the [Google Cloud Console](https://console.cloud.google.com/)
+ Create a new project (or select an existing one). - Create or select a project. + Configure Consent Screen
+ - Go to **APIs & Services** > **OAuth consent screen**.
+ - Select **External** and click **Create**.
+ - Fill in the required App Information (App name, User support email) and click Save.
+ *(You can skip the Scopes and Test Users sections for now)*. - Enable **Google Identity Services**. + 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"). + - Go to **APIs & Services → Credentials**. - - - 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. + **Set Redirect URI (Important)** Scroll down to **Authorized redirect URIs** and click **Add URI**.
+ Enter the URL based on your environment: ```bash copy # Production https://your-domain.com/auth/google/callback @@ -227,456 +377,672 @@ To enable Google login, you need to create OAuth credentials in the ***Google Cl # Development http://localhost:3000/auth/google/callback ``` + > Note: This URL must match exactly what you put in the .env file later. - - Copy the generated **Client ID** and **Client Secret** into your `.env` file. + + Copy **Keys** Click **Create**. A popup will appear with your **Client ID** and **Client Secret**. Copy these values. +**2. Update Environment** + +Open your `.env` file and paste the values you just obtained. + +**Connection Settings** + ```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) +# 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" ``` -- `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.***) - -Use HTTPS for the callback URL in production. - + +**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 (Coming Soon) +##### Apple OAuth +Coming Soon -Apple sign-in support is planned but not yet supported in SpaceDF. +Support for "Sign in with Apple" is currently in development. It is **not enabled in this version** of SpaceDF. - - Do not configure these values yet. - Apple OAuth is **not supported** in the current release. - + + ℹ️ **No Action Required:** You can safely skip this section. Please leave these values blank or commented out in your `.env` file. + ```bash copy -# Apple OAuth (reserved for future use) -APPLE_CLIENT_ID=__APPLE_CLIENT_ID__ -APPLE_CLIENT_SECRET=__APPLE_CLIENT_SECRET__ -APPLE_CLIENT_KEY=__APPLE_CLIENT_KEY__ -APPLE_CERTIFICATE_KEY=__APPLE_CERTIFICATE_KEY__ +# 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 is responsible for user authentication, authorization, and tenant management in SpaceDF. +Required -Set the following values in your `.env` file. -```bash copy -# Replace with your own values. -AUTH_POSTGRES_PASSWORD=__AUTH_POSTGRES_PASSWORD__ -AUTH_SECRET_KEY=__AUTH_SECRET_KEY__ -DEFAULT_TENANT_HOST=__DEFAULT_TENANT_HOST__ -ROOT_API_KEY=__ROOT_API_KEY__ -``` -- `AUTH_POSTGRES_PASSWORD` - The password used by the Auth Service to connect to its ***PostgreSQL database***. (***Use a strong and unique password.***) -- `AUTH_SECRET_KEY` - A secret key used to sign and validate authentication-related data. (***Keep this value private.***) -- `DEFAULT_TENANT_HOST` - The default domain or host assigned to the initial tenant. This is usually your main application domain. -- `ROOT_API_KEY` - A master API key with full access to the Auth Service. Used for administrative or internal operations only. +The Auth Service manages user logins and security. You need to configure its database connection and domain settings. -**Secret keys**: Generate secure random values for secret keys: -```bash copy -openssl rand -hex 32 -``` -Use the generated value for: -```bash copy -AUTH_SECRET_KEY=generated_secret_value -ROOT_API_KEY=generated_root_api_key -``` +**1. Security Credentials** -**Default tenant host** +Set up the password for the database and the encryption key for sessions. -Set this to the domain or host where SpaceDF will be accessed: -```bash copy -DEFAULT_TENANT_HOST=app.spacedf.example -``` + + **Generate a Secret Key**: Run this command in your terminal to get a secure random string: + + ```bash copy + openssl rand -hex 32 + ``` + + + + **Update `.env`**: Copy the generated string and your database password into the file: + + ```bash copy + # 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. + + + ⚠️ **Format Note:** Do not include `http://` or `https://`. Only enter the domain name + + + + + For Localhost: Use this if you are running SpaceDF on your own computer. + ```bash copy + DEFAULT_TENANT_HOST=localhost + ``` + + + + For Live Server: + Use your actual domain name (e.g., `app.spacedf.com` or `spacedf.com`). + ```bash copy + DEFAULT_TENANT_HOST=your-domain.com + ``` + + --- ##### S3 Service -> The Amazon S3 service is used by SpaceDF to store files such as uploads, assets, and generated data. +Required - - SpaceDF supports **Amazon S3 only** for file storage in this setup. - +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. -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. + + ℹ️ **Note:** Currently, SpaceDF supports **Amazon S3 only**.
+ Other providers (like Google Cloud Storage or MinIO) are not yet supported. + -If you do not already have an AWS account, create one at, [see more](https://repost.aws/knowledge-center/create-and-activate-aws-account):
+If you do not already have an AWS account, create one at:
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. +**1. Create an S3 Bucket** -**Create an S3 bucket** +This is the "container" where your files will be stored. - Open the [Amazon S3 Console](https://console.aws.amazon.com/s3/) + Log in to your AWS account and navigate to the [Amazon S3 Console](https://console.aws.amazon.com/s3/) - Create a new bucket + 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. + - 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` - + Finish
+ Scroll to the bottom and click `Create bucket`. Note down your **Bucket Name** and **Region Code**. -Save the bucket name and region for later use. +Refer: [Official AWS Guide on Creating Buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) -Read more: [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket) +**2. Create IAM Credentials** + +Now you need to create a "Service User" that has permission to read/write to that bucket. **Create IAM credentials** - Open the [AWS IAM Console](https://console.aws.amazon.com/iam/) + Open the [AWS IAM Console](https://console.aws.amazon.com/iam/) and click **Users** in the left sidebar. - Create a new **IAM user** + **Add User**
+ Click **Create user**. + * **User name:** Enter a name like `spacedf-s3-user`. + * Click **Next**. - Grant the user access to the S3 bucket
- *Recommended:* grant only required S3 permissions (read/write) + **Set Permissions** + - Select **Attach policies directly**. + - In the search bar, type `AmazonS3FullAccess`. + - Check the box next to `AmazonS3FullAccess` + - Click **Next**, then click **Create user** + > Note: For advanced security, you can create a custom policy restricted to a single bucket later - Create an **Access Key** for the user
- Access Key ID, Secret Access Key + **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**. -Read more: [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) + + ⚠️ **Important:** This is the **only time** you can view the **Secret access key**. Copy it immediately or download the `.csv` file + - -Use IAM policies with **minimum required permissions**. - +Refer: [Managing Access Keys in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) + +**3. Update Environment** + +Open your `.env` file and fill in the values from the previous steps. -**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 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" ``` -- `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***) -- `AWS_STORAGE_BUCKET_NAME` - The name of the S3 bucket where SpaceDF stores files. -- `AWS_REGION` - The AWS region where the S3 bucket is located. (e.g., `us-east-1`, `ap-southeast-1`). +**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 -> Redis is used by SpaceDF for caching and fast data access. +Required -Set the Redis connection URL in the `.env` file. +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**. ```bash copy -# Replace with your own values. REDIS_HOST="redis://redis:6379/1" ``` -- `redis://` — Connection protocol -- `redis` — Redis service name (default in Docker) -- `6379` — Default Redis port -- `/1` — Redis database number - - - - You are using the provided Docker setup - - Redis is running as part of the included Docker Compose file + ❓ **Why** In our Docker setup, the service is named `redis`. SpaceDF automatically finds it at this address. - - - Redis runs on a different server or host - - Redis uses a non-default port - - You want to use a different Redis database + ℹ️ **Syntax with Password:** If your Redis requires a password, follow this format:
+ `redis://:PASSWORD@HOST:PORT/DB_INDEX` ---- -##### Dashboard Service -> The Dashboard Service provides the web interface for managing SpaceDF, including administration and monitoring features. - -**Database password** - -Choose a strong password for the Dashboard Service database: +Example: ```bash copy -# Replace with your own values. -DASHBOARD_POSTGRES_PASSWORD=change_this_to_a_secure_password +# Example for external Redis with password +REDIS_HOST="redis://:mypassword123@192.168.1.50:6379/0" ``` -`DASHBOARD_POSTGRES_PASSWORD` - The password used by the Dashboard Service to connect to its PostgreSQL database. (***Use a strong and unique password***.) -**Secret key**: Generate a secure random value: -```bash -openssl rand -hex 32 -``` -Set it in your `.env` file: +**3. Connection Details** -```bash copy -# Replace with your own values. -DASHBOARD_SECRET_KEY=generated_secret_value -``` -`DASHBOARD_SECRET_KEY` - A secret key used to sign and protect dashboard-related sessions and data. (***Keep this value private.***) +Breakdown of the connection string components: +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Component + + Description + + Example +
`redis://`ProtocolAlways `redis://`
`:password@`(Optional) Password prefix`:secret123@`
`host`Server IP or Domain`localhost` or `192.168.x.x`
`:6379`Port numberDefault is `6379`
`/1`Database Index (0-15)`/1`
+
--- -##### Device Service -> The Device Service manages devices, device data, and communication with telemetry-related services in SpaceDF. +#### Service Credentials +Required -**Database password** - -Choose a strong password for the Device Service database: -```bash copy -# Replace with your own values. -DEVICE_POSTGRES_PASSWORD=change_this_to_a_secure_password -``` +The following services (Dashboard & Device) operate independently. Each requires its own Database Password and unique Secret Key to function securely. -`DEVICE_POSTGRES_PASSWORD` - The password used by the Device Service to connect to its PostgreSQL database. (***Use a strong and unique password***.) + + 🔐 **Security Rule** Do **not reuse** the same password or secret key across different services.
+ Generate a unique value for each variable below. + -**Secret key**: Generate a secure random value: -```bash +**1. Generate Secret Keys** Run this command twice to generate two different keys: +```bash copy openssl rand -hex 32 ``` -Set it in your `.env` file: - +**2. Update `.env`** Update the values for both the Dashboard and Device services. ```bash copy -# Replace with your own values. -DEVICE_SECRET_KEY=generated_secret_value +# --- 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 ``` -`DEVICE_SECRET_KEY` - A secret key used to sign and protect device-related data and requests. (***Keep this value private.***) +--- -**Telemetry service URL** +##### Telemetry service +Required -Defines the internal Docker service address that SpaceDF uses to communicate with the Telemetry Service. +This variable points to the internal Docker container that handles device data. -When using the **default Docker setup**, the Telemetry Service runs as a Docker container and is accessible via its **service name**. +**Configuration** In 99% of cases (Local & Production), you **should keep the default value**. ```bash copy # Default (recommended) -TELEMETRY_SERVICE_URL=http://telemetry-service:8080 +TELEMETRY_SERVICE_URL=http://telemetry: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. + title: "!text-base", + description: "!text-sm" +}} + title="❓ Why" +> + - **No Action Needed:** This service runs automatically inside Docker. + - **Internal Access:** SpaceDF uses this URL to talk to the service internally. It does not need a public domain or HTTPS. -Only change this value if you modify the Telemetry Service name or port in `docker-compose.yml`. +**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 MQTT broker used by SpaceDF to handle device messaging and real-time communication. +Required -Choose a username and a strong password: +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. ```bash copy -# Replace with your own values. EMQX_HOST=http://emqx:18083/api/v5 -EMQX_USERNAME=spacedf -EMQX_PASSWORD=change_this_to_a_secure_password ``` -- `EMQX_HOST` - The base URL of the EMQX Management API used by SpaceDF. This is typically the EMQX service running inside Docker. -- `EMQX_USERNAME` - The username SpaceDF uses to authenticate with the EMQX broker. -- `EMQX_PASSWORD` - The password for the EMQX user above. (***Use a strong and unique password***.) + +**2. Admin Credentials** Define the username and password SpaceDF will use to log in to EMQX. +```bash copy +EMQX_USERNAME=your_secure_username +EMQX_PASSWORD=your_secure_password +``` + + + ⚠️ **Consistency:** These credentials must match the admin user defined in your EMQX configuration (or Dashboard). + --- ##### Broker Bridge Service -> The Broker Bridge Service connects SpaceDF to an external MQTT broker or bridges messages between brokers. +Required -**Broker credentials** +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). ```bash copy -# Replace with your own values. -MQTT_BROKER_BRIDGE_USERNAME=bridge-user -MQTT_BROKER_BRIDGE_PASSWORD=change_this_to_a_secure_password +MQTT_BROKER_BRIDGE_USERNAME=your_bridge_username +MQTT_BROKER_BRIDGE_PASSWORD=your_bridge_password ``` -- `MQTT_BROKER_BRIDGE_USERNAME` - The username used to authenticate with the external MQTT broker. -- `MQTT_BROKER_BRIDGE_PASSWORD` - The password for the broker bridge user. (***Keep this value private***.) +**2. Topic Subscription** -**MQTT topics** +Define which MQTT topics SpaceDF should listen to. -Specify one or more topics, separated by commas. ```bash copy -# Replace with your own values. MQTT_TOPICS=device/+/telemetry,device/+/status ``` -`MQTT_TOPICS` - A list of MQTT topics that SpaceDF subscribes to or bridges. + +**Syntax Guide:** +- Comma (`,`): Use to separate multiple topics. +- Plus (`+`): Wildcard for a single level (e.g., matching any device ID). +- Hash (`#`): Wildcard for all remaining levels. + + + 📝 **Example:** `device/+/telemetry` will match `device/sensor-01/telemetry` and `device/sensor-02/telemetry`. + --- -##### AWS to access to SES service -> SpaceDF uses email services to send system emails such as account verification, password resets, and notifications. +##### Email Service (AWS SES) +Required -This setup commonly uses **AWS Simple Email Service (SES)**, but can be adapted to other SMTP-compatible providers. +SpaceDF uses AWS SES (Simple Email Service) to send account verification emails, password resets, and notifications. -**How to get AWS SES credentials** - - Sign in to the [AWS Console](https://aws.amazon.com/console/) - - - Open **Simple Email Service (SES)**. +**1. Setup & Verify** + +Before sending emails, you must tell AWS which email address or domain you own. + + + **Go to SES Console**
+ Log in to AWS and open the [Amazon SES Console](https://console.aws.amazon.com/ses/). - - Verify your domain or sender email address. + + +**Verify Identity** +* Go to **Configuration** -> **Verified identities**. +* Click **Create identity**. +* Choose **Email address** (easiest) or **Domain**. +* Check your inbox and click the verification link sent by AWS. - - Create **SMTP credentials** in SES: -
    -
  • - These are different from your AWS access keys. -
    • -
+ +Refer: [AWS Guide on Verifying Identities](https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html) + +**2. Get SMTP Credentials** + + + ⚠️ **Crucial Distinction:** Do **not** use your standard AWS Access Keys.
+ You must generate specific **SMTP Credentials**. + + + +**Create Credentials** +* Go to **SMTP Settings** in the left sidebar. +* Click the button **Create SMTP credentials**. - - Copy the SMTP username and password into: -
    -
  • - `EMAIL_HOST_USER` -
    • -
  • - `EMAIL_HOST_PASSWORD` -
    • -
+ + +**Copy Keys** +* Click **Create**. +* Download the credentials or copy the **SMTP Username** and **SMTP Password** immediately. -Set the following values in your `.env` file. +Refer: [AWS Guide on Obtaining SMTP Credentials](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html) + +**3. Update Environment** + +Update the `.env` file with the SMTP credentials you just created. ```bash copy -# Replace with your own values. -EMAIL_HOST_USER=AKIAXXXXXXXX -EMAIL_HOST_PASSWORD=XXXXXXXXXXXXXXXX -DEFAULT_FROM_EMAIL=no-reply@spacedf.example +# 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" ``` -- `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. + +**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 SpaceDF to an MQTT broker to receive and publish messages for application-level processing. +Required + +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. -Example: MQTT broker running in Docker ```bash copy -# Replace with your own values. -MQTT_BROKER=emqxl +# --- Connection Settings --- +# Hostname (Use 'emqx' if running inside Docker) +MQTT_BROKER=emqx +# Port (1883 for TCP, 8883 for SSL/TLS) MQTT_PORT=1883 -MQTT_USERNAME=mpa -MQTT_PASSWORD=change_this_to_a_secure_password -MQTT_CLIENT_ID=spacedf-mpa +# Unique name for this client +MQTT_CLIENT_ID=spacedf-mpa-client +# Topics to subscribe to (use '+' for wildcards) MQTT_TOPIC=devices/+/events -``` -- `MQTT_BROKER` - The hostname or IP address of the MQTT broker. -- `MQTT_USERNAME` - The username used to authenticate with the MQTT broker. -- `MQTT_PASSWORD` - The password for the MQTT user. (***Keep this value private***.) -- `MQTT_PORT` - The port used to connect to the MQTT broker (e.g., `1883` for plain TCP, `8883` for TLS). -- `MQTT_CLIENT_ID` - A unique client identifier for the MPA Service when connecting to MQTT. -- `MQTT_TOPIC` - The MQTT topic the MPA Service subscribes to. - - - Use TLS (`8883`) in production if available
- Restrict broker permissions to required topics only - ---- -##### Bootstrap Service -> 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** - -This value defines the **base URL** where the Bootstrap (Backend) service is accessible. -```bash copy -# Local development (default) -HOST=http://localhost:8000 -``` -For production deployments, set this to your **public API domain**: -```bash copy -# Replace with your public API domain. -HOST=https://api.spacedf.example +# --- Authentication --- +MQTT_USERNAME=mpa_user +MQTT_PASSWORD=change_this_to_secure_password ``` -`HOST` - The public base URL where the Bootstrap Service is accessible. This is used by other services to communicate with it. +**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. - - - HOST in your `.env` file - - The backend port in `docker-compose.yml` +}} + title="⚠️ Production Tips:" +> + - **Use TLS:** In a live environment, change the port to 8883 for encrypted connections. + - **Client ID:** Ensure `MQTT_CLIENT_ID` is unique. If you run multiple instances of SpaceDF, they cannot share the same ID +--- +##### Bootstrap Service +Required -**CORS origins** +The Bootstrap Service is the **main backend API of SpaceDF**. It orchestrates the system setup and handles requests from your frontend applications. -List all frontend origins that should be allowed to access the service. -Separate multiple values with commas. +**1. API URL (`HOST`)** -Development (local) -```bash copy -# Local development (default) -CORS_ALLOWED_ORIGINS=http://localhost,http://localhost:3000,http://localhost:3001 -``` +This variable defines the public address where your Backend API is accessible. -Production -```bash copy -# Replace with your own values. -CORS_ALLOWED_ORIGINS=https://app.spacedf.example,https://admin.spacedf.example -``` + + + For Localhost: Use this default value if you are running SpaceDF on your computer. + ```bash copy + HOST=http://localhost:8000 + ``` + -`CORS_ALLOWED_ORIGINS` - A comma-separated list of allowed origins for cross-origin requests. This controls which frontend domains can access the Bootstrap Service. + + For Public Domain: Set this to your actual API domain. + ```bash copy + HOST=https://api.yourdomain.com + ``` - - **Important notes** - - Controls **which frontend domains can access** the Bootstrap service - - Each frontend **must be listed explicitly**, including protocol and port - - If you change frontend ports in `docker-compose.yml`, update both the Docker ports and `CORS_ALLOWED_ORIGINS` - + + ⚠️ **Requirement:** In production, you should use HTTPS for security. . + + + -Example: +**2. Access Control (`CORS`)** -If the Dashboard is moved from port `3000` to `4000`, you must add: +This setting controls which websites (frontends) are allowed to talk to your backend. -```text copy -http://localhost:4000 -``` -to `CORS_ALLOWED_ORIGINS`. +This prevents unauthorized websites from using your API. -**Secret key**: Generate a secure random value: -```bash -openssl rand -hex 32 -``` + + - List all frontend URLs exactly (including `http/https` and port). + - Separate multiple URLs with a comma (`,`) and `no spaces`. + + + + + **Allow Local Ports:** List all the local ports your frontend apps use (e.g., Dashboard on `3000`, Admin portal on `3001`). + ```bash copy + CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 + ``` + -Set it in your `.env` file: + + **Allow Public Domains:** List your actual frontend domains (App and Admin). + ```bash copy + CORS_ALLOWED_ORIGINS=https://app.yourdomain.com,https://admin.yourdomain.com + ``` + + -```bash copy -# Replace with your own values. -BOOTSTRAP_SECRET_KEY=generated_secret_value -``` -`BOOTSTRAP_SECRET_KEY` - A secret key used to secure internal Bootstrap operations. (***Keep this value private.***) + + - If you change a frontend port (e.g., from `3000` to `4000`) in `docker-compose.yml`, you must update this list to include `http://localhost:4000` + - If you forget, the app will show a `Network Error` or `CORS-ERROR`. + + +**3. Security Key** + +This key secures the internal operations of the backend. + + + **Generate Key** + ```bash copy +openssl rand -hex 32 + ``` + + + + **Update `.env`** + ```bash copy +BOOTSTRAP_SECRET_KEY=paste_your_generated_key_here + ``` + --- ##### Organization Initialization -> These settings are used to create the **initial organization and owner account** when SpaceDF starts for the first time. This step runs only during the first startup. +Required + +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. ```bash copy # Replace with your own values. -ORG_NAME=SpaceDF -ORG_SLUG=spacedf -OWNER_EMAIL=admin@spacedf.example -OWNER_PASSWORD=change_this_to_a_secure_password +ORG_NAME="My IoT Company" +OWNER_EMAIL="admin@your-domain.com" +OWNER_PASSWORD="change_this_to_a_secure_password" ``` -- `ORG_NAME` - The display name of your organization. -- `ORG_SLUG` - A short, URL-friendly identifier for the organization (lowercase, no spaces). -- `OWNER_EMAIL` - The email address of the initial organization owner. -- `OWNER_PASSWORD` - The password for the owner account. (***Use a strong and 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**. + + + These `.env` values are only read during the initial installation. + * **To change Password/Email:** Log in to the Dashboard and go to Profile Settings. + * **To change Organization Name:** Log in to the Dashboard and go to **Organization Settings**.
+ (Modifying the `.env` file after installation will have no effect). + + + + ⭐ **Branding:** The `ORG_NAME` helps brand your system immediately. In production, you can point your **custom domain** (e.g., `iot.your-brand.com`) to the server to fully white-label the platform. + --- 🎉 You have now finished configuring the backend services.
@@ -684,220 +1050,476 @@ 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)*. + - The Admin Portal is used for **system-level** and **organization-level** administration.
- This application is typically accessed by **platform administrators**, not end users. + container: "!mt-6 !p-3 shadow-none", + title: "!text-base", + description: "!text-sm" + }} + > + SpaceDF uses `NextAuth.js` for its authentication layer. If you need to customize behavior or debug specific issues, please refer to the official documentation: + - [NextAuth.js Documentation](https://next-auth.js.org/) - General guide and concepts. + - [Environment Variables](https://next-auth.js.org/configuration/options) - Detailed list of all available options. + - [Security Guide](https://next-auth.js.org/security) - Best practices for securing your authentication. -Configure these environment variables to connect the Admin Portal to backend services and authentication providers. - - - **Before continuing**
- Make sure you have completed the **Backend Services Configuration** above.
- The Admin Portal depends on backend authentication and API services. - -##### Authentication + + ⚠️ **Prerequisite Check:** Please ensure you have fully configured the **Backend Services** section above.
+ The Admin Portal cannot function without a running backend. + -**Generate NextAuth secret** +##### Authentication & URLs +Required -Open the [following link](https://generate-secret.vercel.app/32) in your browser to generate a secure random secret: +This section secures user sessions and defines the public address of your Admin Portal. -Copy the generated value and set it in your `.env` file: +**1. Generate Secret Key** Create a unique key to encrypt login sessions. Run this command in your terminal: ```bash copy -# Replace with your own values. -PORTAL_NEXTAUTH_SECRET=4f7c2a9e8d1b6c3f0a... +openssl rand -hex 32 ``` -`PORTAL_NEXTAUTH_SECRET` - A secret key used by NextAuth to encrypt sessions and tokens. (***Keep this value private.***) -**Admin Portal URL** +Update the value in your `.env` file: -Development ```bash copy -HOST_FRONTEND_ADMIN=http://localhost:3001 -PORTAL_NEXTAUTH_URL=http://localhost:3001 +# Replace with the generated string +PORTAL_NEXTAUTH_SECRET=your_generated_secret_key ``` -Production -```bash copy -HOST_FRONTEND_ADMIN=https://admin.spacedf.example -PORTAL_NEXTAUTH_URL=https://admin.spacedf.example -``` +**2. Configure Domain** Set the URL where administrators will access the portal. + + + + For Localhost: Use this setup if you are running the portal on your computer. + ```bash copy + HOST_FRONTEND_ADMIN=http://localhost:3001 + PORTAL_NEXTAUTH_URL=http://localhost:3001 + ``` + + + For Public Domain: Replace with your actual domain name. + ```bash copy + HOST_FRONTEND_ADMIN=https://admin.yourdomain.com + PORTAL_NEXTAUTH_URL=https://admin.yourdomain.com + ``` + + ⚠️ **Consistency:** In most cases, these two variables must be identical. + + + + +**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. -- `HOST_FRONTEND_ADMIN` - The public URL where the Admin Portal is accessible. -- `PORTAL_NEXTAUTH_URL` - The base URL used by NextAuth for redirects and callbacks.
This value should match the Admin Portal public URL. --- -##### API Access +##### Backend Connection (API) -**Using Docker** -```bash copy -PORTAL_AUTH_API=http://haproxy:3000 -``` +The Admin Portal needs to communicate with the Backend API to handle user authentication and data retrieval. -**External API** -```bash copy -# Replace with your own values. -PORTAL_AUTH_API=https://api.spacedf.example -``` +**Choose your deployment scenario:** -`PORTAL_AUTH_API` - The backend API endpoint used by the Admin Portal for authentication.
-This typically points to the internal API gateway or load balancer. + + + **Scenario: All-in-One (Docker Compose)** If you are running both the Frontend and Backend on the same server using our provided Docker setup, use the internal service name. + ```bash copy + # Connects internally via the Docker network + PORTAL_AUTH_API=http://haproxy:3000 + ``` + + ❓ **Why not localhost** Inside a Docker container, `localhost` refers to the container itself, not your computer. Using `haproxy` allows the Portal to find the API within the internal Docker network. + + ---- -##### References + + **Scenario: Distributed / External** Use this only if your Backend is hosted on a different server or if you are deploying the Frontend to a service like Vercel/Netlify. + ```bash copy + # 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. + + + - [NextAuth.js Documentation](https://next-auth.js.org/) - General guide and concepts. + - [Environment Variables](https://next-auth.js.org/configuration/options) - Detailed list of all available options. + - [Security Guide](https://next-auth.js.org/security) - Best practices for securing your authentication. + -Use the official documentation below if you need more details about **NextAuth** behavior or advanced configuration: -- [NextAuth.js Documentation](https://next-auth.js.org/) -- [NextAuth Environment Variables](https://next-auth.js.org/configuration/options) -- [NextAuth Security Guide](https://next-auth.js.org/security) --- ### Dashboard Configuration -This section configures the **SpaceDF Dashboard**, the main web interface used for daily operations, device monitoring, and data visualization. +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. - - **Before continuing**
- Make sure you have completed the **Backend Services Configuration** above.
- The Dashboard depends on backend APIs, MQTT, and authentication services. - + + SpaceDF uses `NextAuth.js` for its authentication layer. If you need to customize behavior or debug specific issues, please refer to the official documentation: + - [NextAuth.js Documentation](https://next-auth.js.org/) - General guide and concepts. + - [Environment Variables](https://next-auth.js.org/configuration/options) - Detailed list of all available options. + - [Security Guide](https://next-auth.js.org/security) - Best practices for securing your authentication. + -##### Authentication + + ⚠️ **Prerequisite Check:** Please ensure you have fully configured the **Backend Services** section above.
+ The Dashboard requires the Backend API and MQTT Broker to be running to fetch data. + -**Generate NextAuth secret** +##### Authentication & URLs +Required -Open the [following link](https://generate-secret.vercel.app/32) in your browser to generate a secure random secret: +This section secures user sessions and defines the public address of your Dashboard. -Copy the generated value and set it in your `.env` file: +**1. Generate Secret Key** Create a unique key to encrypt login sessions. Run this command in your terminal: ```bash copy -# Replace with random secret. -DASHBOARD_NEXTAUTH_SECRET=4f7c2a9e8d1b6c3f0a... - -# The public URL where the Dashboard is accessible. -DASHBOARD_NEXTAUTH_URL=http://localhost:3000 +openssl rand -hex 32 ``` -- `DASHBOARD_NEXTAUTH_SECRET` - A secret key used by NextAuth to encrypt sessions and tokens. (***Keep this value private.***) -- `DASHBOARD_NEXTAUTH_URL` - The public URL where the Dashboard is accessible.
-This value is used for redirects and callbacks. ---- -##### API Access -**Using Docker** -```bash copy -DASHBOARD_AUTH_API=http://haproxy:3000 -``` +Update the value in your `.env` file: -**External API** ```bash copy -# Replace with your own values. -DASHBOARD_AUTH_API=https://api.spacedf.example +# 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. + + + + For Localhost: Use this setup if you are running the dashboard on your computer + ```bash copy + DASHBOARD_NEXTAUTH_URL=http://localhost:3000 + ``` + + + For Public Domain: Replace with your actual domain name. + ```bash copy + DASHBOARD_NEXTAUTH_URL=https://dashboard.yourdomain.com + ``` + + ⚠️ **HTTPS:** In production, ensure your domain is secured with SSL (HTTPS) + + + + +**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) +Required + +The Dashboard needs to communicate with the Backend API to fetch user data, device status, and charts. + +**Choose your deployment scenario:** + + + + **Scenario: All-in-One (Docker Compose)** If you are running both the Dashboard and Backend on the same server using our Docker setup, use the internal service name. + ```bash copy + # Connects internally via the Docker network + DASHBOARD_AUTH_API=http://haproxy:3000 + ``` + + ℹ️ **Network Note:** Do not use `localhost` here. Inside the Docker network, `haproxy` is the correct hostname to reach the API gateway. + + + + + **Scenario: Distributed / External** Use this **only** if your Backend is hosted on a different server or if you are deploying the Dashboard to a cloud provider (e.g., Vercel, Netlify). + ```bash copy + # 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 -> The Dashboard uses **MapTiler** as a map service to resolve location names from coordinates and support location-based features. +Optional + +SpaceDF uses **MapTiler** to provide map visualization and **Reverse Geocoding** (converting GPS coordinates into readable addresses like "123 Main St"). + + + ℹ️ **What happens if I skip this?** The Dashboard will **still work**, but you will **not see street addresses**.
+ Locations will only be displayed as raw latitude/longitude coordinates (e.g., `10.762`, `106.660`). + + +**Setup Instructions:** -**How to get a MapTiler API key** - Create a MapTiler account: [MapTiler](https://www.maptiler.com/) + **Create Account**
+ Sign up for a free account at [MapTiler](https://www.maptiler.com/) - Go to your dashboard and create an **API key**. + **Get API Key**
+ Go to the **Keys** section in your **MapTiler dashboard** and copy your **Default Key**. - Copy the key and set it as `MAPTILER_API_KEY`. + **Update `.env`**
+ Paste the key into your `.env` file. + ```bash copy + # Replace with your API Key. + MAPTILER_API_KEY=__MAPTILER_API_KEY__ + ``` -```bash copy -# Replace with your API Key. -MAPTILER_API_KEY=__MAPTILER_API_KEY__ -``` +[MapTiler Documentation](https://docs.maptiler.com/) + --- ##### MQTT (Real-time Data) -> The Dashboard connects to MQTT to receive real-time device data. +Required -**Recommended values**
-**Development** -```bash copy -DASHBOARD_MQTT_PROTOCOL=ws -DASHBOARD_MQTT_PORT=8883 -DASHBOARD_MQTT_BROKER=emqx.localhost:8000 -``` +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. -**Production** -```bash copy -# Use wss (secure WebSocket) in production. -DASHBOARD_MQTT_PROTOCOL=wss -DASHBOARD_MQTT_PORT=443 -DASHBOARD_MQTT_BROKER=emqx.example.com -``` +**Configuration by Environment:** -- `DASHBOARD_MQTT_USERNAME` / `DASHBOARD_MQTT_PASSWORD` - Credentials used by the Dashboard to connect to the MQTT broker. -- `DASHBOARD_MQTT_PROTOCOL` - Protocol used for MQTT connections.
-Use ws (WebSocket) for browser-based clients. -- `DASHBOARD_MQTT_PORT` - Port exposed by the MQTT broker for WebSocket connections. -- `DASHBOARD_MQTT_BROKER` - Host and port of the MQTT broker accessible from the browser. + + + For Localhost: Use `ws` (Unencrypted WebSocket) for local development. + ```bash copy + # 1. Connection Details + DASHBOARD_MQTT_PROTOCOL=ws + DASHBOARD_MQTT_PORT=8083 + DASHBOARD_MQTT_BROKER=localhost + + # 2. Public Auth (Read-Only User recommended) + DASHBOARD_MQTT_USERNAME=dashboard_user + DASHBOARD_MQTT_PASSWORD=your_password + ``` + > (Note: Ensure Port `8083` is exposed in your EMQX Docker container). + + + + For Production: You **must** use `wss` (Secure WebSocket). Browsers will block insecure `ws` connections if your site is loaded over `https`. + ```bash copy + # 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: `8083` for ws, `8084` for wss). + + + ⚠️ **Browser Security Rule:** If your Dashboard runs on **HTTPS** (Production), you cannot use ws (insecure).
+ You MUST use `wss`. Failing to do so will cause "Mixed Content" errors, and the connection will fail. + + +[MQTT over WebSocket](https://www.emqx.com/en/blog/connect-to-mqtt-broker-with-websocket) + +--- + +
+

+ 🎉 Configuration Fully Complete! +

+
+ You have successfully configured the Backend APIs, Admin Portal, and User Dashboard. Your SpaceDF environment is ready. +
+
+ 👉 Next Step: Proceed to the Starting the Services section to launch your platform. +
+
- - Use HTTPS and `wss` in production environments
- Restrict MQTT permissions to read-only topics for the Dashboard - --- -##### References -- [NextAuth.js Documentation](https://next-auth.js.org/) -- [MapTiler Documentation](https://docs.maptiler.com/) -- [MQTT over WebSocket](https://www.emqx.com/en/blog/connect-to-mqtt-broker-with-websocket) ## Starting and Stopping -> This section explains how to start, check, and stop SpaceDF services using Docker Compose. -### Starting the services -From the directory that contains your `./entrypoint.sh` file, run: +This section explains how to manage the lifecycle of your SpaceDF instance using standard Docker commands. + + + ⚠️ **Prerequisite:** Ensure your `.env` file is fully configured and saved in the root directory before running these 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:** ```bash copy -# Start all services in the background +# 1. Grant execution permission (First time only) chmod +x entrypoint.sh + +# 2. Start the system ./entrypoint.sh ``` -Docker will start all SpaceDF services in detached mode. +**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. + + + 🔍 **Troubleshooting:** If you see a `Permission denied` error, ensure you have run the `chmod +x` command successfully. + ### Checking service status -After starting, you can check the status of all services: +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: + ```bash copy 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: -```scss copy -Up (healthy) +```text +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 ``` + + ℹ️ **Note on "starting" status:** If you see `Up (starting)`, it means the service is still initializing (e.g., waiting for the database). Wait a moment and run the command again. + + + + 🔍 **Troubleshooting:** If any service shows `Exited (1) or Unhealthy`, please check the logs using: `docker compose logs -f <service_name>` + + ### Troubleshooting startup issues -If a service shows a status like `created` or does not become Up, check its logs to see what went wrong. +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. -For example, to view logs for a specific service: ```bash copy -docker compose logs analytics +# Syntax: docker compose logs -f +docker compose logs -f backend ``` -Review the logs for errors such as missing environment variables or connection issues. +- `-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: + +| Error Type | Log Message Example | Solution | +|----------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------| +| Missing Config | `KeyError: 'DATABASE_URL' or Config validation failed` | Check your `.env` file. A required variable is missing or empty. | +| Connection | `Connection refused or PGSQL connection failed` | The service cannot reach a dependency (like the Database). Wait a moment, or check if it runs. | +| Permission | `EACCES: permission denied` | File permission issue (often happens with scripts). Run `chmod +x` on entry scripts. | + + + ⭐ **Pro Tip:** If you see `Connection refused` immediately after starting, wait 10-20 seconds. Sometimes services start faster than the Database, causing a temporary error before they automatically retry and succeed. + ### Stopping the services -To stop all running SpaceDF services, run: + +To gracefully shut down the SpaceDF platform and release system resources, run the following command: + ```bash copy docker compose down ``` -This stops and removes the containers but keeps your data volumes intact. - - **Notes** - - Starting and stopping services may take a short time - - Always check service status after starting - - Stop services before making configuration changes - +**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**. + + + - **When to stop:** It is recommended to stop the services before making major changes to the `.env` file or `docker-compose.yml`. + - **Restarting:** To apply new configurations or updates, simply run `./entrypoint.sh` (or `docker compose up -d`) again after stopping. + + + + ⛔ **Caution:** Do not use the `-v` flag (e.g., `docker compose down -v`) unless you intend to **permanently delete** all your data and start from scratch. + + ## Accessing SpaceDF Services -> After all services are running, you can access SpaceDF through the web interfaces and backend APIs using the URLs below. + +Once all containers are running successfully, you can access the various components of the SpaceDF platform using the URLs below.
@@ -936,31 +1558,71 @@ This stops and removes the containers but keeps your data volumes intact.
- - **Notes** - - Make sure all services show **Up (healthy)** before accessing them - - Use HTTPS in production environments - - Ensure firewall and reverse proxy settings allow access to the required ports - + + - **Apps (Dashboard/Admin):** Log in using the `OWNER_EMAIL` and `OWNER_PASSWORD` you defined in the `.env` file. + - **EMQX Console:** Log in using `admin` / `public` (Default) or the credentials defined in `EMQX_PASSWORD`. + + +**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 publishes stable updates for the Docker Compose setup on a regular basis. -To update your self-hosted deployment, pull the latest changes from the repository and restart the services. +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. + + + ⚠️ **Downtime Notice:** The update process requires restarting Docker containers. Your services will be temporarily unavailable (usually for a few seconds to a minute) during the restart phase. Plan accordingly. + -> Updating services requires restarting containers and may cause temporary downtime. +**Standard Update Procedure** + +Run the following commands in your terminal to upgrade your deployment. -### General update process - Pull the latest changes from the SpaceDF repository. + **Fetch Latest Configuration**
+ Update your local repository to get the latest `docker-compose.yml` and script changes. + ```bash copy + git pull origin main + ``` - - Pull updated Docker images. + + + **Download Updated Images**
+ Pull the latest versions of the SpaceDF Docker images. + ```bash copy + docker compose pull + ``` - - Restart the services. + + + **Apply & Restart**
+ Recreate the containers with the new images. + ```bash copy + docker compose up -d + ``` + > (Note: Docker will only restart containers that have updates). -In most cases, this is enough to apply the latest updates. + + ⭐ **Cleanup (Optional):** After a major update, you can remove old, unused images to free up disk space: `docker image prune -f` + ### 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. @@ -970,87 +1632,129 @@ You can run a specific version of a service by changing its Docker image tag in This approach is recommended only if you know exactly what you are doing. -#### Update or rollback a single service +### 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`. + + + ⛔ **Compatibility Risk:** SpaceDF services are designed to work together as a suite. Running mixed versions (e.g., a simplified Dashboard with an advanced Backend) may lead to **API errors**, **database conflicts**, or **data corruption**. + + **Only proceed if you understand the dependencies**. + + +**Procedure: Update a Single Service** + +Follow these steps to update (or downgrade) a specific component, for example, the **Dashboard**. -For example, if you want to update or roll back the Dashboard service: - Check available images and tags on the [SpaceDF container registry](https://github.com/orgs/Space-DF/packages). + **Find the Version Tag**
+ Visit the [SpaceDF Container Registry](https://github.com/orgs/Space-DF/packages) to find the exact tag you need (e.g., `v2026.01.21`). - Choose a version tag (for example: `v2026.01.21`). - - - Update the image field in `docker-compose.yml` - ```yml copy - image: ghcr.io/space-df/spacedf-web-app:v2026.01.21 + **Edit Configuration**
+ Open `docker-compose.yml` and locate the service (e.g., `dashboard`). Replace the image tag with your chosen version. + ```yml copy + services: + dashboard: + # Change the tag after the colon + image: ghcr.io/space-df/spacedf-web-app:v2026.01.21 ``` - - Apply the changes: + + **Apply Changes (Smart Restart)**
+ Run the following commands to pull and restart **only** the target service, leaving the rest of the system running. ```bash copy - docker compose pull - docker compose down - docker compose up -d - ``` + # 1. Pull the specific image + docker compose pull dashboard + + # 2. Recreate only this container + docker compose up -d dashboard + ``` -The service will restart using the specified version. + + ❓ **Why not use `docker compose down`** Using `down` stops the entire platform. By targeting `up -d dashboard`, you only restart the Dashboard, ensuring that the Backend and MQTT Broker continue to process device data without interruption. + -### Notes on downtime -- Services must be restarted to apply updates -- Active users may experience brief downtime -- Consider performing updates during low-traffic periods +### Maintenance Strategy & Resources -### Staying up to date -- To track changes, fixes, and new features, refer to: - - SpaceDF release notes -- The self-hosting changelog in the repository +Managing updates effectively is key to maintaining a stable IoT platform. -## Uninstalling + + - **Restart Required:** Applying updates always requires restarting the Docker containers. + - **Service Interruption:** Active users will experience a brief disconnection (typically 10-60 seconds) while the containers re-initialize. + - **Best Time to Update:** We strongly recommend scheduling maintenance during **low-traffic periods** (e.g., late night or weekends) to minimize the impact on your operations. + - - **Warning**
- The steps below will permanently delete all SpaceDF data, including databases and storage volumes.
- Make sure you have backups before continuing. - +**Staying Up to Date:** To track the latest features, security patches, and bug fixes, please consult our official channels: +- [SpaceDF Release Notes](https://docs.spacedf.com/blog): High-level overview of new features and major changes. +- [GitHub Changelog](https://github.com/Space-DF): Detailed technical log of all changes in the self-hosted repository. -### Stop and remove services -From the directory that contains your `docker-compose.yml` file, run: -```bash copy -# Stop all services and remove containers and volumes -docker compose down -v -``` +## Uninstalling -This command stops all SpaceDF services and removes all associated Docker volumes. +This section guides you through completely removing SpaceDF from your server. -### (Optional) Remove remaining data manually -In some cases, you may want to ensure all data directories are fully removed. + + - User accounts and passwords. + - All device data and history. + - System configurations. + - Uploaded files. + -**Remove database data** -```bash copy + +### Wipe Containers & Volumes + Run the following command in your project directory to stop services and destroy their internal data volumes. + ```bash copy + # The '-v' flag ensures volumes are deleted + docker compose down -v + ``` +### Clean Host Directories (Optional) +Docker might leave some mounted files on your host machine (usually inside the `volumes/ folder`). To ensure a 100% clean state, remove them manually. + +```bash copy +# Remove Database files rm -rf volumes/db/data -``` -**Remove storage data** -```bash copy +# Remove File Storage (Uploads/Images) rm -rf volumes/storage ``` + -**What gets removed** -- All SpaceDF services -- All databases and stored data -- All uploaded files and assets +### Verification -After these steps, SpaceDF is completely removed from your system. +At this point, SpaceDF is completely removed. +- Containers: Stopped and deleted. +- Networks: Removed. +- Data: Wiped. - - **Notes** - - These actions **cannot be undone** - - Use this only if you want a clean uninstall - - For reinstallation, follow the setup guide from the beginning - - -## Demo + + ℹ️ **Reinstallation:** If you want to start fresh, simply run the setup guide from the beginning. The system will treat it as a brand new installation. + ## Need Help? diff --git a/src/content/getting-started/self-hosting/docker/quick-start.mdx b/src/content/getting-started/self-hosting/docker/quick-start.mdx index d6e5be0..40eece6 100644 --- a/src/content/getting-started/self-hosting/docker/quick-start.mdx +++ b/src/content/getting-started/self-hosting/docker/quick-start.mdx @@ -8,7 +8,7 @@ import { CardInfo } from "@/app/_components/CardInfo.jsx" # Quick Start -> This guide helps you get **SpaceDF running quickly** on your own infrastructure using **Docker Compose** and **default settings**. +This guide helps you get **SpaceDF running quickly** on your own infrastructure using **Docker Compose** and **default settings**.
    @@ -117,7 +117,8 @@ After startup, SpaceDF services are available on the following default ports: Make sure these ports are open on your server and not used by other services. ### Default account (Quick Start only) -> Quick Start creates default accounts for initial access + +Quick Start creates default accounts for initial access These accounts are for **local testing only**. diff --git a/src/content/getting-started/self-hosting/index.mdx b/src/content/getting-started/self-hosting/index.mdx index 76fb78e..2ce6566 100644 --- a/src/content/getting-started/self-hosting/index.mdx +++ b/src/content/getting-started/self-hosting/index.mdx @@ -8,7 +8,7 @@ import { RichCardOptions, RichCardOption } from "@/app/_components/RichCard.jsx" # Self-Hosting -> Install and run your own SpaceDF platform on your computer, server, or cloud infrastructure. +Install and run your own SpaceDF platform on your computer, server, or cloud infrastructure. ---