Sign inSign up

cargofy/atlas

By cargofy

•Updated 7 months ago

Image
1

323

cargofy/atlas repository overview

⁠ATLAS Docker Guide

⁠Quick Start

docker run -p 3000:3000 cargofy/atlas

Open http://localhost:3000⁠ — the Setup Wizard will guide you through configuration.

Health check: http://localhost:3000/api/health⁠

⁠Production Setup

Create a docker-compose.yml:

services:
  atlas:
    image: cargofy/atlas:latest
    container_name: atlas
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - atlas_data:/data/atlas
      - ./knowledge:/app/knowledge
      - ./inbox:/app/inbox
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/api/health').then(r=>{if(!r.ok)throw r;process.exit(0)}).catch(()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  atlas_data:
# Create .env with your API keys
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Start
docker compose up -d

# View logs
docker compose logs -f atlas
⁠Docker Run
docker run -d \
  --name atlas \
  --restart unless-stopped \
  -p 3000:3000 \
  -v atlas_data:/data/atlas \
  -v ./knowledge:/app/knowledge \
  -v ./inbox:/app/inbox \
  -v ./config.yml:/app/config.yml:ro \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  cargofy/atlas:latest

⁠Volumes

Mount PointPurpose
/data/atlasSQLite database (persistent). Use a named volume to survive container restarts
/app/knowledgeKnowledge base markdown files. Bind-mount to access/edit from host
/app/inboxInbox folder for file-watch module. Drop files here for auto-processing
/app/config.ymlConfiguration file (mount read-only)

⁠Environment Variables

VariableDescriptionDefault
ANTHROPIC_API_KEYAnthropic API key for Claude models—
OPENAI_API_KEYOpenAI API key (optional)—
ATLAS_DB_PATHSQLite database file path/data/atlas/atlas.db
ATLAS_PORTHTTP server port3000
EMAIL_PASSWORDEmail connector password (if using IMAP)—
TMS_API_KEYTMS API connector key—

⁠Configuration

Copy the example config and customize:

# Get config template from the image
docker run --rm cargofy/atlas cat config.example.yml > config.yml

Edit config.yml to configure AI providers, connectors, modules, auth tokens, and data models. Then mount it into the container.

Configuration can also be edited live via the Settings page in the Web UI.

⁠MCP over stdio (Claude Desktop)

For Claude Desktop integration, run ATLAS in stdio mode:

{
  "mcpServers": {
    "atlas": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "atlas_data:/data/atlas",
        "cargofy/atlas",
        "node", "src/index.js"
      ]
    }
  }
}

⁠Image Details

  • Base: node:20-alpine
  • Multi-stage build: build tools (python3, make, g++) are not included in the final image
  • Non-root: runs as unprivileged atlas user
  • Health check: built-in via node -e fetch(...) (no curl dependency)
  • Size: ~180MB compressed

⁠Tags

TagDescription
latestLatest stable release
0.1First versioned release

⁠Troubleshooting

Container starts but Web UI shows nothing

Check logs: docker logs atlas. Verify port mapping with docker ps.

Database errors on restart

Ensure /data/atlas is mounted as a persistent volume. Without it, SQLite data is lost when the container stops.

AI features not working

Set ANTHROPIC_API_KEY or OPENAI_API_KEY via environment variables, or configure models in config.yml / Settings UI.

File-watch module not picking up files

Mount your inbox directory to /app/inbox and ensure the file-watch module is enabled in config or the Modules page.

Tag summary

Content type

Image

Digest

sha256:79b51c22a…

Size

71.7 MB

Last updated

7 months ago

docker pull cargofy/atlas