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 8 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
23 changes: 22 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,32 @@ 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
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.

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 thread
coderabbitai[bot] marked this conversation as resolved.

Comment on lines +97 to +124
Copy link
Copy Markdown
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.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
- **[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
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.
Comment thread
NiveditJain marked this conversation as resolved.
55 changes: 55 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,55 @@
services:
mongodb:
image: mongo:7.0
container_name: mongodb
restart: unless-stopped
Comment thread
NiveditJain marked this conversation as resolved.
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}
Comment thread
NiveditJain marked this conversation as resolved.
volumes:
- mongodb_data:/data/db
ports:
- "27017:27017"
Comment on lines +12 to +13
Copy link
Copy Markdown
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
Comment thread
coderabbitai[bot] marked this conversation as resolved.

Comment thread
NiveditJain marked this conversation as resolved.
exosphere-state-manager:
image: ghcr.io/exospherehost/exosphere-state-manager:latest
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
container_name: exosphere-state-manager
restart: unless-stopped
environment:
- MONGO_URI=${MONGO_URI:-mongodb://admin:password@mongodb:27017/exosphere?authSource=admin}
- STATE_MANAGER_SECRET=${STATE_MANAGER_SECRET:-exosphere@123}
- MONGO_DATABASE_NAME=${MONGO_DATABASE_NAME:-exosphere}
- SECRETS_ENCRYPTION_KEY=${SECRETS_ENCRYPTION_KEY:-YTzpUlBGLSwm-3yKJRJTZnb0_aQuQQHyz64s8qAERVU=}
Comment thread
NiveditJain marked this conversation as resolved.
Outdated
depends_on:
- mongodb
Comment thread
NiveditJain marked this conversation as resolved.
Outdated
ports:
- "8000:8000"
networks:
- exosphere-network
Comment thread
NiveditJain marked this conversation as resolved.

exosphere-dashboard:
image: ghcr.io/exospherehost/exosphere-dashboard:latest
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:-WhatPeopleWant}
- NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY:-exosphere@123}
Comment thread
NiveditJain marked this conversation as resolved.
Outdated
depends_on:
Comment thread
NiveditJain marked this conversation as resolved.
Outdated
- exosphere-state-manager
ports:
- "3000:3000"
networks:
- exosphere-network

volumes:
mongodb_data:
driver: local

networks:
exosphere-network:
driver: bridge
attachable: true
34 changes: 34 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,34 @@
services:
exosphere-state-manager:
image: ghcr.io/exospherehost/exosphere-state-manager:latest
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
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=}
Comment thread
NiveditJain marked this conversation as resolved.
ports:
- "8000:8000"
networks:
- exosphere-network

Comment thread
coderabbitai[bot] marked this conversation as resolved.
exosphere-dashboard:
image: ghcr.io/exospherehost/exosphere-dashboard:latest
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:-WhatPeopleWant}
- NEXT_PUBLIC_DEFAULT_API_KEY=${NEXT_PUBLIC_DEFAULT_API_KEY:-exosphere@123}
Comment thread
NiveditJain marked this conversation as resolved.
Outdated
depends_on:
- exosphere-state-manager
ports:
- "3000:3000"
networks:
- exosphere-network

Comment on lines +39 to +45
Copy link
Copy Markdown
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)

Mirror healthcheck command style for the dashboard.

Consistency and clearer failures.

-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3000"]
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://localhost:3000 >/dev/null || 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", "curl", "-f", "http://localhost:3000"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:3000 >/dev/null || exit 1"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
🤖 Prompt for AI Agents 
In docker-compose/docker-compose.yml around lines 39 to 45, the service
healthcheck uses the array form ["CMD", "curl", "-f", "http://localhost:3000"]
which differs from the dashboard's healthcheck style; change the test to use the
same shell-style pattern (CMD-SHELL) and the same curl flags and failure
handling (e.g., use curl -fsS with an explicit failure exit) so the healthcheck
command style, flags, and behavior mirror the dashboard while leaving interval,
timeout, retries and start_period unchanged.

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