A self-hosted business platform that brings CRM, HRM, invoicing, agreements, documents, projects & tasks, file storage, and whiteboards into one connected workspace for your team. An open alternative to Zoho and Odoo.

Live demo: app.dodoapps.net · Docker image: ghcr.io/gorkem-bwl/atlas (multi-arch amd64 + arm64) · Releases: github.com/gorkem-bwl/atlas/releases

macOS / Linux:

git clone https://github.com/gorkem-bwl/atlas.git
cd atlas
chmod +x setup.sh
./setup.sh

Windows (PowerShell):

git clone https://github.com/gorkem-bwl/atlas.git
cd atlas
powershell -ExecutionPolicy Bypass -File setup.ps1

This will:

1. Generate secure secrets automatically
2. Start PostgreSQL, Redis, and Atlas via Docker
3. Wait for the service to be healthy

Then open http://localhost:3001 and create your admin account.

git clone https://github.com/gorkem-bwl/atlas.git
cd atlas
docker compose -f docker-compose.production.yml up -d

Open http://localhost:3001 and create your admin account. Secrets are auto-generated on first run.

To pin a specific version: IMAGE_TAG=<version> docker compose -f docker-compose.production.yml up -d — see the latest release for the current tag.

# 1. Set your domain in .env
echo 'ATLAS_DOMAIN=atlas.yourdomain.com' >> .env

# 2. Point your domain's DNS A record to your server's IP

# 3. Start with HTTPS
docker compose -f docker-compose.production.yml -f docker-compose.https.yml up -d

Caddy automatically obtains and renews Let's Encrypt SSL certificates. Ports 80 and 443 must be open.

# 1. Start PostgreSQL and Redis
docker compose up -d

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env

# 4. Update .env for local development:
#    - DATABASE_URL=postgresql://postgres:postgres@localhost:5432/atlas
#    - CLIENT_PUBLIC_URL=http://localhost:5180
#    - CORS_ORIGINS=http://localhost:5180,http://localhost:3001
#    The JWT secrets in .env.example are placeholders — generate real ones:
#      openssl rand -hex 32  → paste into JWT_SECRET
#      openssl rand -hex 32  → paste into JWT_REFRESH_SECRET
#      openssl rand -hex 32  → paste into TOKEN_ENCRYPTION_KEY

# 5. Start dev servers
npm run dev

• Client: http://localhost:5180
• Server: http://localhost:3001
• On first visit, you'll be prompted to create an admin account.

Atlas exposes an OpenAPI 3.1 specification and an interactive reference UI:

• Raw spec: http://localhost:3001/api/v1/openapi.json
• Interactive reference (Scalar): http://localhost:3001/api/v1/reference

The spec is generated from Zod schemas in packages/server/src/openapi/paths/. When a route adopts defineRoute(), the same schema drives both the OpenAPI registration and runtime request validation — so documentation and wire contract cannot drift.

On a self-hosted deployment, replace localhost:3001 with your Atlas domain.

CRM — Pipeline, contacts, companies, deals, leads, forecasting, saved views, web-to-lead forms	HRM — Employees, departments, org chart, leave management, attendance
Work — Projects, tasks, time tracking, billing, reports, budgets	Calendar — Month/week/day/year/agenda views with Google Calendar sync
Invoices — Invoice creation, recurring billing, templates, payment tracking	Agreements — PDF contracts with e-signatures, templates, counterparty linking, sequential signing, audit trail, reminders
Drive — File storage with versioning, sharing, comments, activity log, password-protected links	Write — Rich text editor with cover images, comments, templates
System — CPU/memory/disk monitoring, email settings, role-based app permissions

Atlas also includes Draw — an Excalidraw-based canvas with PDF export, image insertion, and presentation mode.

Data import. Bring your CRM data with you. Atlas ships with an Odoo importer (Settings → Data import) that ingests res.partner, crm.lead, and CRM activity CSV exports — mapping companies, contacts, leads, deals, and activities into your tenant in one pass, with per-row validation and a skipped-row report. HubSpot is on the way.

• Frontend: React, TypeScript, Vite, TanStack Query, Zustand
• Backend: Express, TypeScript, Drizzle ORM, PostgreSQL
• Infrastructure: Docker, Redis, BullMQ

Atlas boots with a small set of required secrets. Everything else is optional and only enables specific features — see the What needs what table below.

The Docker setup.sh / setup.ps1 scripts generate all three for you on first run. If you use docker-compose.production.yml directly, the compose file auto-generates them as well. You only need to set them manually when running Atlas outside Docker (e.g. development, or a custom deploy).

Atlas is designed so you only pay for the integrations you want. If you skip the optional variables above, the affected features silently become unavailable — the rest of the app keeps working.

If you plan to run Atlas as a closed team tool with no email needs, you can skip SMTP and Google entirely. Users just won't receive emails (invitations have to be shared as links manually) and /calendar, /crm, /drive will work locally without Google sync.

Atlas sends email (it never receives). SMTP is used for:

• Password reset links
• Team-member invitations (POST /auth/invitation)
• Agreement reminders (hourly scheduler, Sign app)
• CRM outbound messages from the CRM email composer
• The "Send test email" button in Settings → System

If SMTP_HOST is not set, all of the above are logged and skipped — no errors, features that depend on them just can't deliver.

# Gmail (requires an App Password, not your regular password — enable 2FA first)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@yourdomain.com
SMTP_PASS=your-16-char-app-password
SMTP_FROM=Atlas <you@yourdomain.com>

# SendGrid
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.your-api-key
SMTP_FROM=Atlas <noreply@yourdomain.com>

# Resend
SMTP_HOST=smtp.resend.com
SMTP_PORT=587
SMTP_USER=resend
SMTP_PASS=re_your-api-key
SMTP_FROM=Atlas <noreply@yourdomain.com>

# Postmark
SMTP_HOST=smtp.postmarkapp.com
SMTP_PORT=587
SMTP_USER=<server-token>
SMTP_PASS=<server-token>
SMTP_FROM=Atlas <noreply@yourdomain.com>

After editing .env, restart Atlas and click Settings → System → Send test email to verify delivery.

Atlas uses Google OAuth on a per-user basis. Each user clicks Connect Google in their own Settings to grant access — the admin only has to provide the OAuth client ID/secret once. Without Google set up, /calendar still works (events live in Postgres), CRM email features are hidden, and Drive works for Atlas-native files only.

1. Open Google Cloud Console and create or select a project.
2. APIs & Services → Library — enable:
   • Gmail API
   • Google Calendar API
   • Google Drive API
3. APIs & Services → OAuth consent screen — configure:
   • User type: External (unless you're on Google Workspace, in which case Internal is simpler).
   • App name, support email, developer contact.
   • While in Testing status you can only authenticate accounts listed under Test users. For a single-company deployment that's often enough. If you want anyone in your org (or the public) to be able to connect, click Publish app — note that the sensitive scopes (gmail.readonly, gmail.send) require Google verification before the app leaves In production warning state.
4. APIs & Services → Credentials → Create credentials → OAuth 2.0 Client ID:
   • Application type: Web application.
   • Authorized redirect URI: https://your-atlas-domain/api/v1/auth/google/callback (use http://localhost:3001/api/v1/auth/google/callback for local dev).

GOOGLE_CLIENT_ID=xxxxxxxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxx
# Optional — only needed if the server's public URL differs from the OAuth redirect host
# GOOGLE_REDIRECT_URI=https://your-atlas-domain/api/v1/auth/google/callback

Restart Atlas. The Connect Google option appears in Settings → Integrations for each user.

On the initial connection:

• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.send
• https://www.googleapis.com/auth/calendar.readonly
• https://www.googleapis.com/auth/calendar.events

Drive scopes are requested incrementally only when the user first opens the Drive integration, so users who never touch Drive don't grant those:

• https://www.googleapis.com/auth/drive.readonly
• https://www.googleapis.com/auth/drive.file

Tokens are encrypted at rest with TOKEN_ENCRYPTION_KEY before being written to Postgres.

If REDIS_URL is also set, Atlas enables a BullMQ worker that keeps user Gmail/Calendar in sync outside the request path (periodic pull, webhook delivery). Without Redis, sync happens on-demand when users open the CRM or Calendar views — still functional, just not ambient.

"network ... not found" error

docker compose -f docker-compose.production.yml down
docker compose -f docker-compose.production.yml up -d

Port 3001 already in use

Stop the process using port 3001, or set a different port in .env:

PORT=3002

Update to latest version

docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Reset everything (fresh start)

docker compose -f docker-compose.production.yml down -v
docker compose -f docker-compose.production.yml up -d

• 2 GB RAM + 4 GB swap (or 4 GB RAM)
• 1 vCPU
• 10 GB disk
• Docker 20+ with Compose plugin

• 4 GB RAM
• 2 vCPU
• 20 GB disk

Tip: On 2 GB machines, add swap before building:

sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

GNU Affero General Public License v3.0 — free to use, modify, and distribute. If you run a modified version as a network service, you must make the source available to users.