Skip to content

Enhance Docker Compose setup and documentation #332

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
NiveditJain merged 11 commits into from
Sep 1, 2025
Merged

Enhance Docker Compose setup and documentation #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
61a1846
Enhance Docker Compose setup and documentation
NiveditJain Sep 1, 2025
d5107ad
Update docker-compose/README.md
NiveditJain Sep 1, 2025
a1cae1b
Update docker-compose/README.md
NiveditJain Sep 1, 2025
8a7e5ed
Update docs/docs/docker-compose-setup.md
NiveditJain Sep 1, 2025
21fa0db
Update docs/docs/docker-compose-setup.md
NiveditJain Sep 1, 2025
5dde9a8
Refactor Docker Compose README for clarity and conciseness
NiveditJain Sep 1, 2025
a18f26d
Update container names in Docker Compose files for consistency
NiveditJain Sep 1, 2025
c87bf05
Remove MongoDB dependency from Docker Compose configuration and fix f…
NiveditJain Sep 1, 2025
924f35b
Enhance Docker Compose configuration and documentation
NiveditJain Sep 1, 2025
13c1f2e
Update health checks in Docker Compose files and enhance documentation
NiveditJain Sep 1, 2025
a2f7a5d
Add Docker Compose setup documentation and update navigation
NiveditJain Sep 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,11 +94,39 @@ This allows developers to deploy production agents that can scale beautifully to
}
```

## Quick Start with Docker Compose

Get Exosphere running locally in under 2 minutes:

```bash
# Option 1: With cloud MongoDB (recommended)
echo "MONGO_URI=your-mongodb-connection-string" > .env
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
docker compose up -d

# Option 2: With local MongoDB (development)
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
docker compose -f docker-compose-with-mongodb.yml up -d
```

**Environment Configuration:**
- Docker Compose automatically loads `.env` files from the working directory
- Create your `.env` file in the same directory as your docker-compose file

> **⚠️ Security Note**: Variables prefixed with `NEXT_PUBLIC_` are embedded in client bundles and visible to browsers. Never store real secrets in `NEXT_PUBLIC_` variables - use server-side environment variables instead.

Access your services:

- **Dashboard**: `http://localhost:3000`
- **API**: `http://localhost:8000`

> **📝 Note**: This configuration is for **development and testing only**. For production deployments, environment variable customization, and advanced configuration options, please read the complete **[Docker Compose Setup Guide](https://docs.exosphere.host/docker-compose-setup)**.

Comment on lines +97 to +124
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

⚠️ Potential issue

Great Quick Start; tweak .env phrasing and list spacing.

Compose loads .env from the working directory (where you run docker compose), not strictly “the same directory as your compose file.” Also add a blank line before the bullet list to satisfy MD032.

 **Environment Configuration:**
-- Docker Compose automatically loads `.env` files from the working directory
-- Create your `.env` file in the same directory as your docker-compose file
+ 
+- Docker Compose automatically loads a `.env` file from the working directory (where you run `docker compose`)
+- Create your `.env` file in the same directory where you execute `docker compose`
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Quick Start with Docker Compose
Get Exosphere running locally in under 2 minutes:
```bash
# Option 1: With cloud MongoDB (recommended)
echo "MONGO_URI=your-mongodb-connection-string" > .env
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml
docker compose up -d
# Option 2: With local MongoDB (development)
curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml
docker compose -f docker-compose-with-mongodb.yml up -d
```
**Environment Configuration:**
- Docker Compose automatically loads `.env` files from the working directory
- Create your `.env` file in the same directory as your docker-compose file
> **⚠️ Security Note**: Variables prefixed with `NEXT_PUBLIC_` are embedded in client bundles and visible to browsers. Never store real secrets in `NEXT_PUBLIC_` variables - use server-side environment variables instead.
Access your services:
- **Dashboard**: `http://localhost:3000`
- **API**: `http://localhost:8000`
> **📝 Note**: This configuration is for **development and testing only**. For production deployments, environment variable customization, and advanced configuration options, please read the complete **[Docker Compose Setup Guide](https://docs.exosphere.host/docker-compose-setup)**.
**Environment Configuration:**
- Docker Compose automatically loads a `.env` file from the working directory (where you run `docker compose`)
- Create your `.env` file in the same directory where you execute `docker compose`
> **⚠️ Security Note**: Variables prefixed with `NEXT_PUBLIC_` are embedded in client bundles and visible to browsers. Never store real secrets in `NEXT_PUBLIC_` variables—use server-side environment variables instead.
🧰 Tools
🪛 LanguageTool

[grammar] ~97-~97: Use correct spacing
Context: ... ``` ## Quick Start with Docker Compose Get Exosphere running locally in under 2...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

[grammar] ~99-~99: Use correct spacing
Context: ...here running locally in under 2 minutes: bash # Option 1: With cloud MongoDB (recommended) echo "MONGO_URI=your-mongodb-connection-string" > .env curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose.yml docker compose up -d # Option 2: With local MongoDB (development) curl -O https://raw.githubusercontent.com/exospherehost/exospherehost/main/docker-compose/docker-compose-with-mongodb.yml docker compose -f docker-compose-with-mongodb.yml up -d Environment Configuration: - Docker Co...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

[grammar] ~112-~112: There might be a mistake here.
Context: ... up -d ``` Environment Configuration: - Docker Compose automatically loads `.env...

(QB_NEW_EN)

[grammar] ~113-~113: There might be a mistake here.
Context: ... .env files from the working directory - Create your .env file in the same dire...

(QB_NEW_EN_OTHER)

[grammar] ~114-~114: There might be a mistake here.
Context: ...me directory as your docker-compose file > ⚠️ Security Note: Variables prefixed w...

(QB_NEW_EN_OTHER)

[typographical] ~116-~116: To join two clauses or set off examples, consider using an em dash.
Context: ...er store real secrets in NEXT_PUBLIC_ variables - use server-side environment variables inste...

(QB_NEW_EN_DASH_RULE_EM)

[grammar] ~116-~116: Use correct spacing
Context: ...rver-side environment variables instead. Access your services: - Dashboard: ...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

[grammar] ~118-~118: Use correct spacing
Context: ...ariables instead. Access your services: - Dashboard: http://localhost:3000 - *...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

[grammar] ~120-~120: There might be a mistake here.
Context: ...Access your services: - Dashboard: http://localhost:3000 - API: http://localhost:8000 > **📝 N...

(QB_NEW_EN)

[grammar] ~121-~121: Use correct spacing
Context: ...d**: http://localhost:3000 - API: http://localhost:8000 > 📝 Note: This configuration is for **d...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

[grammar] ~123-~123: Use correct spacing
Context: ....exosphere.host/docker-compose-setup)**. ## Documentation For comprehensive documen...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

🪛 markdownlint-cli2 (0.17.2)

113-113: Lists should be surrounded by blank lines

(MD032, blanks-around-lists)

🤖 Prompt for AI Agents 
In README.md around lines 97 to 124, update the .env wording and spacing: change
the sentence that says "Create your `.env` file in the same directory as your
docker-compose file" to clarify that Docker Compose loads `.env` from the
working directory where you run `docker compose` (not necessarily the compose
file directory), and insert a single blank line before the "Environment
Configuration:" bullet list to satisfy MD032; keep the existing security note
and access URLs unchanged.

## Documentation

For comprehensive documentation and guides, check out:


- **[Docker Compose Setup](https://docs.exosphere.host/docker-compose-setup)**: Complete guide for running Exosphere locally with Docker Compose.
- **[Getting Started Guide](https://docs.exosphere.host/getting-started)**
- **[State Manager Setup Guide](https://docs.exosphere.host/exosphere/state-manager-setup)**: Step-by-step instructions for running the Exosphere backend locally or in production.
- **[Dashboard Guide](https://docs.exosphere.host/exosphere/dashboard)**: Learn how to set up and use the Exosphere web dashboard.
Expand Down
2 changes: 1 addition & 1 deletion dashboard/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ NEXT_PUBLIC_DEV_MODE=true
npm run dev
```

5. **Open your browser** and navigate to [http://localhost:3000](http://localhost:3000)
5. **Open your browser** and navigate to `http://localhost:3000`
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Fix ordered list numbering to satisfy markdownlint (MD029).

Use “1.” style for all items in ordered lists.

-5. **Open your browser** and navigate to `http://localhost:3000`
+1. **Open your browser** and navigate to `http://localhost:3000`
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
5. **Open your browser** and navigate to `http://localhost:3000`
1. **Open your browser** and navigate to `http://localhost:3000`
🧰 Tools
🪛 LanguageTool

[grammar] ~69-~69: Use correct spacing
Context: .... Open your browser and navigate to http://localhost:3000 ### Environment Configuration The dashboard...

(QB_NEW_EN_OTHER_ERROR_IDS_5)

🪛 markdownlint-cli2 (0.17.2)

69-69: Ordered list item prefix
Expected: 1; Actual: 5; Style: 1/1/1

(MD029, ol-prefix)

🤖 Prompt for AI Agents 
In dashboard/README.md around line 69, the ordered list uses explicit
incremental numbers (e.g., "5.") which triggers markdownlint MD029; update the
list to use the "1." style for every ordered item (or at least change the "5."
at line 69 to "1.") so all ordered list entries consistently use "1." and
satisfy MD029.


### Environment Configuration

Expand Down
4 changes: 4 additions & 0 deletions docker-compose/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Exosphere Docker Compose Setup

This directory contains Docker Compose files for running Exosphere locally.
For detailed setup instructions, please refer to the **[Docker Compose Setup Guide](https://docs.exosphere.host/docker-compose-setup)** in our official documentation.
77 changes: 77 additions & 0 deletions docker-compose/docker-compose-with-mongodb.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
services:
mongodb:
image: mongo:7.0
container_name: exosphere-mongodb
restart: unless-stopped
environment:
MONGO_INITDB_ROOT_USERNAME: ${MONGO_INITDB_ROOT_USERNAME:-admin}
MONGO_INITDB_ROOT_PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD:-password}
MONGO_INITDB_DATABASE: ${MONGO_INITDB_DATABASE:-exosphere}
volumes:
- mongodb_data:/data/db
ports:
- "27017:27017"
Comment on lines +12 to +13
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Consider not publishing MongoDB to the host (optional).

For local dev, you usually don’t need 27017 exposed; reduces attack surface.

-    ports:
-      - "27017:27017"
+    # ports:
+    #   - "27017:27017"  # Uncomment only if you need host access (e.g., MongoDB Compass)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
ports:
- "27017:27017"
services:
mongodb:
image: mongo:7.0
container_name: exosphere-mongodb
restart: unless-stopped
environment:
MONGO_INITDB_ROOT_USERNAME: ${MONGO_INITDB_ROOT_USERNAME:-admin}
MONGO_INITDB_ROOT_PASSWORD: ${MONGO_INITDB_ROOT_PASSWORD:?Set MONGO_INITDB_ROOT_PASSWORD in .env}
MONGO_INITDB_DATABASE: ${MONGO_INITDB_DATABASE:-exosphere}
volumes:
- mongodb_data:/data/db
- ports:
# ports:
# - "27017:27017" # Uncomment only if you need host access (e.g., MongoDB Compass)
healthcheck:
test: ["CMD-SHELL", "mongosh --quiet --eval \"db.adminCommand({ ping: 1 }).ok\" | grep 1"]
interval: 10s
timeout: 5s
retries: 8
networks:
- exosphere-network
🤖 Prompt for AI Agents 
In docker-compose/docker-compose-with-mongodb.yml around lines 12 to 13 the
compose file publishes MongoDB's port 27017 to the host which is unnecessary for
local dev and increases attack surface; remove the ports mapping or comment it
out so MongoDB is only reachable by other services in the compose network, or
alternatively document/run with an environment flag to enable host binding when
explicitly needed (e.g., for external tooling), ensuring the default
configuration does not expose 27017 to the host.

networks:
- exosphere-network
healthcheck:
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s

exosphere-state-manager:
image: ghcr.io/exospherehost/exosphere-state-manager:${EXOSPHERE_TAG:-latest}
pull_policy: always
container_name: exosphere-state-manager
restart: unless-stopped
environment:
- MONGO_URI=${MONGO_URI:-mongodb://admin:password@exosphere-mongodb:27017/}
- STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET:-exosphere@123}
- MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME:-exosphere}
- SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY:-YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=}
depends_on:
mongodb:
condition: service_healthy
ports:
- "8000:8000"
networks:
- exosphere-network
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s

exosphere-dashboard:
image: ghcr.io/exospherehost/exosphere-dashboard:${EXOSPHERE_TAG:-latest}
pull_policy: always
container_name: exosphere-dashboard
restart: unless-stopped
environment:
- NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL=${NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL:-http://exosphere-state-manager:8000}
- NEXT_PUBLIC_DEFAULT_NAMESPACE=${NEXT_PUBLIC_DEFAULT_NAMESPACE:-default}
- NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY}
depends_on:
exosphere-state-manager:
condition: service_healthy
ports:
- "3000:3000"
networks:
- exosphere-network
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s

volumes:
mongodb_data:
driver: local

networks:
exosphere-network:
driver: bridge
attachable: true
49 changes: 49 additions & 0 deletions docker-compose/docker-compose.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
services:
exosphere-state-manager:
image: ghcr.io/exospherehost/exosphere-state-manager:${EXOSPHERE_TAG:-latest}
pull_policy: always
container_name: exosphere-state-manager
restart: unless-stopped
environment:
- MONGO_URI=${MONGO_URI}
- STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET:-exosphere@123}
- MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME:-exosphere}
- SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY:-YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=}
ports:
- "8000:8000"
networks:
- exosphere-network
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
Comment on lines +16 to +21
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Unify healthcheck style with curl (optional).

Use CMD-SHELL + curl for clearer errors and parity with other services (if curl exists in the image).

-    healthcheck:
-      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://localhost:8000/health || exit 1"]
       interval: 10s
       timeout: 5s
       retries: 5
       start_period: 30s
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:8000/health || exit 1"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
🤖 Prompt for AI Agents 
In docker-compose/docker-compose.yml around lines 16 to 21, the healthcheck uses
a Python one-liner; replace it with a CMD-SHELL style healthcheck that calls
curl (e.g. curl -fS to fail on non-2xx and show errors) to match other services
and provide clearer error messages, and if the image may not include curl ensure
the Dockerfile installs curl so the healthcheck will run; keep existing
interval/timeout/retries/start_period values unchanged.


exosphere-dashboard:
image: ghcr.io/exospherehost/exosphere-dashboard:${EXOSPHERE_TAG:-latest}
pull_policy: always
container_name: exosphere-dashboard
restart: unless-stopped
environment:
- NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL=${NEXT_PUBLIC_EXOSPHERE_STATE_MANAGER_URL:-http://exosphere-state-manager:8000}
- NEXT_PUBLIC_DEFAULT_NAMESPACE=${NEXT_PUBLIC_DEFAULT_NAMESPACE:-default}
- NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY}
depends_on:
exosphere-state-manager:
condition: service_healthy
ports:
- "3000:3000"
networks:
- exosphere-network
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s

networks:
exosphere-network:
driver: bridge
attachable: true
Loading