- );
- const pageMap = await getPageMap();
+ )
+ const pageMap = await getPageMap()
return (
-
+
+ +
+
+
+
+
+
+## Installing SpaceDF
+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
+
+# Switch to your project directory
+cd spacedf-project
+
+# Pull the latest images
+docker compose pull
+```
+
+## Configuring and securing SpaceDF
+
+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.
+
+| + Resource + | ++ Minimum + | ++ Recommended + | +
|---|---|---|
| RAM | +4 GB | +8 GB+ | +
| CPU | +2 cores | +4 cores+ | +
| Disk | ++ 20 GB available + | ++ 80 GB+ SSD + | +
-
+
- + Application type: **Web application** + +
- + Authorized redirect URI: + ```string copy + https://your-domain.com/auth/google/callback + ``` + +
-
+
- + Create a bucket in your AWS account + +
- + Note the **bucket name** and **region** + +
-
+
- + Create an IAM user with access to the bucket + +
- + Generate an **Access Key ID** and **Secret Access Key** + +
-
+
- + These are different from your AWS access keys. + +
-
+
- + `EMAIL_HOST_USER` + +
- + `EMAIL_HOST_PASSWORD` + +
+Next, continue with the frontend (web app) configuration.
+ Make sure you have completed the **Backend Services Configuration** above.
+ The Admin Portal depends on backend authentication and API services. +
This value should match the Admin Portal public URL. + +##### API Access + +**Using Docker** +```bash copy +PORTAL_AUTH_API=http://haproxy:3000 +``` + +**External API** +```bash copy +# Replace with your own values. +PORTAL_AUTH_API=https://api.spacedf.example +``` + +`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. + +
+ Make sure you have completed the **Backend Services Configuration** above.
+ The Dashboard depends on backend APIs, MQTT, and authentication services. +
+This value is used for redirects and callbacks. + +##### API Access + +**Using Docker** +```bash copy +DASHBOARD_AUTH_API=http://haproxy:3000 + +# This key must match the value configured on the backend. +SPACE_API_KEY=__SPACE_API_KEY__ +``` + +**External API** +```bash copy +# Replace with your own values. +DASHBOARD_AUTH_API=https://api.spacedf.example + +# This key must match the value configured on the backend. +SPACE_API_KEY=__SPACE_API_KEY__ +``` + +##### Map Services +> The Dashboard uses **MapTiler** as a map service to resolve location names from coordinates and support location-based features. + +```bash copy +# Replace with your API Key. +MAPTILER_API_KEY=__MAPTILER_API_KEY__ +``` + +**How to get a MapTiler API key** +
+**Development** +```bash copy +DASHBOARD_MQTT_PROTOCOL=ws +DASHBOARD_MQTT_PORT=8883 +DASHBOARD_MQTT_BROKER=emqx.localhost:8000 +``` + +**Production** +```bash copy +# Use wss (secure WebSocket) in production. +DASHBOARD_MQTT_PROTOCOL=wss +DASHBOARD_MQTT_PORT=443 +DASHBOARD_MQTT_BROKER=emqx.example.com +``` + +- `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. + +
+ This approach is recommended only if you know exactly what you are doing. +
+ The steps below will permanently delete all SpaceDF data, including databases and storage volumes.
+ Make sure you have backups before continuing. +