OpenCrowd — Quick Start Guide¶

Get OpenCrowd running in 5 minutes. This guide covers installation, first login, user management, and connecting your first application.

1. Install & Start¶

# Clone the repository
git clone https://github.com/opencrowd-io/opencrowd.git
cd opencrowd

# Copy the environment file
cp .env.example .env

# Start everything (PostgreSQL, Redis, Keycloak, Backend, Frontend)
cd infrastructure/docker
docker compose up -d

Wait about 60 seconds for all services to start. Check status:

docker compose ps

All containers should show "healthy" or "running."

2. Access the Application¶

3. First Login¶

OpenCrowd uses Keycloak for authentication. The administrator credentials are what you configured in your .env file.

1. Open http://localhost:3000
2. You'll be redirected to Keycloak login
3. Log in with the credentials configured in your .env file
4. You're now in OpenCrowd as "Platform Admin"

Important: Never use default or weak passwords. Store your credentials in a password manager.

4. User Management (Keycloak)¶

All user accounts are managed in Keycloak — not inside OpenCrowd itself. OpenCrowd handles governance (who has access to what), while Keycloak handles identity (who can log in).

Change the admin password¶

1. Go to http://localhost:8180
2. Log in with the credentials from your .env file
3. Select realm: opencrowd
4. Go to Users → click on the admin user
5. Credentials tab → Set new password

Create a new user¶

1. In Keycloak Admin → Users → Add User
2. Fill in username, email, first/last name
3. Credentials tab → set a password (turn off "Temporary")
4. Role Mappings tab → assign roles:
5. manage_connectors — can manage applications, approve requests, see all data
6. default-roles-opencrowd — basic access (view dashboard, submit requests)
7. The user can now log into OpenCrowd at http://localhost:3000

Roles explained¶

5. Connect Your First Application¶

Now that you're logged in, connect xWiki, OpenProject, or Nextcloud.

1. Go to Applications (left sidebar)
2. Click Add Connector
3. Enter the Base URL, username, and password for your app
4. Click Save → then Health Check
5. Once connected, click Sync to import users and groups

See Connect applications for detailed instructions per application.

6. Explore¶

After your first sync, check:

• Dashboard — Governance overview, risk alerts, connected apps
• Identity — All users from all connected apps
• Groups — All groups across apps
• Access Matrix — Unified permission view (who has what, where)
• Requests — Access request form (also public at /request)
• Audit — Full activity log

7. Next Steps¶

Environment Variables (.env)¶

Key settings you may want to change:

# Keycloak admin (change before production!)
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=<your-strong-random-password>

# Edition: community | professional | enterprise
OPENCROWD_EDITION=community

# Email notifications (optional)
SPRING_MAIL_HOST=smtp.yourprovider.com
SPRING_MAIL_PORT=587
SPRING_MAIL_USERNAME=notifications@company.com
SPRING_MAIL_PASSWORD=your-smtp-password
OPENCROWD_NOTIFICATIONS_ENABLED=true
OPENCROWD_NOTIFICATIONS_ADMIN_EMAIL=admin@company.com

# AI assistant (optional, Professional+ only)
OPENCROWD_MISTRAL_API_KEY=your-mistral-api-key

Architecture¶

┌──────────────────────────────────────────────────────────────┐
│  Your Browser                                                │
│  http://localhost:3000                                        │
└─────────────────────────────┬────────────────────────────────┘
                              │
┌─────────────────────────────▼────────────────────────────────┐
│  Frontend (React + TypeScript)                       :3000   │
│  Serves UI, proxies API calls to backend                     │
└─────────────────────────────┬────────────────────────────────┘
                              │
┌─────────────────────────────▼────────────────────────────────┐
│  Backend (Kotlin + Spring Boot)                      :8080   │
│  REST API, business logic, connectors, sync engine           │
└──────┬──────────────┬──────────────┬─────────────────────────┘
       │              │              │
┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ PostgreSQL  │ │  Valkey   │ │ Keycloak  │
│ (data)      │ │  (cache)  │ │ (auth)    │
│ :5432       │ │  :6379    │ │ :8180     │
└─────────────┘ └───────────┘ └───────────┘
       │
       │  Backend connects outbound to:
       │
┌──────▼──────────────────────────────────────────────────────┐
│  Your Applications                                           │
│  ┌─────────┐  ┌──────────────┐  ┌───────────┐              │
│  │  xWiki  │  │ OpenProject  │  │ Nextcloud │              │
│  └─────────┘  └──────────────┘  └───────────┘              │
└──────────────────────────────────────────────────────────────┘

Stopping & Restarting¶

# Stop all services (data preserved)
docker compose down

# Stop and delete all data (fresh start)
docker compose down -v

# Restart
docker compose up -d

Troubleshooting¶