On this page
Set up WorkSpace in 30 minutes
This guide takes you from a fresh server to a fully running WorkSpace - with email, AI, and your first team members. Follow the steps in order; each one builds on the last.
Before you begin
Make sure your server meets these requirements before running the installer.
| Requirement | Minimum | Notes |
|---|---|---|
| OS | Ubuntu 22.04 LTS | Also works on Debian 12, Rocky Linux 9 |
| CPU | 2 vCPU | 4 vCPU recommended for AI features |
| RAM | 2 GB | 4 GB recommended; 8 GB if running Ollama local AI |
| Disk | 20 GB SSD | Grows with email data; 40 GB comfortable |
| Docker | 20.10+ | Install guide ↗ |
| Docker Compose | v2.0+ | Included with Docker Desktop; docker compose version to check |
| Ports open | 80, 443, 8080 | Also 25, 587, 993 for email (optional) |
| Domain name | Recommended | Required for HTTPS and email delivery; can start with IP |
Installation steps
Run the one-line installer on your server. It launches an interactive wizard that checks your environment, asks a few questions, and starts all services automatically.
curl -fsSL https://karyospace.com/install.sh | bashThe wizard will ask for:
- Organisation name - displayed in the app header and emails
- Your domain - e.g.
workspace.acme.com(used for URLs and email) - Admin email - the first administrator account
- Okta SSO credentials - optional, can be added later
- AI provider - Groq (cloud, fastest) or Ollama (local, private)
All cryptographic secrets (session keys, DKIM keys, database passwords) are generated automatically. Nothing sensitive is sent anywhere - everything stays on your server.
Verify the install completed
The installer performs a health check automatically. Once you see the green SUCCESS banner, WorkSpace is running. Confirm with:
# Check running containers
docker compose ps
# Check application health
curl -s http://localhost:8080/healthA healthy response looks like: {"status":"ok"}
Open your browser and navigate to your domain (or http://localhost:8080 if you haven't set up a domain yet). You'll be redirected to the login page.
If you configured Okta
Click Sign in with Okta. On first login with the admin email you provided, WorkSpace automatically grants you admin privileges based on the ADMIN_USERS env variable — no separate account creation needed.
If you skipped Okta (development / testing)
WorkSpace includes a dev login shortcut for non-production environments. Make sure your .env has APP_ENV=development and DEV_LOGIN=true, then navigate directly to:
http://localhost:8080/dev/login?as=admin@yourcompany.comADMIN_USERS env variable — any email listed there receives admin rights on login, regardless of auth method. To create additional user accounts after your first login, use the admin panel at /admin → Users → New User, or POST /auth/local/register with an active admin session.Explore the admin panel
Navigate to /admin after logging in. From here you can:
- Manage users, roles, and permissions
- View AI query logs and usage metrics
- Monitor email delivery and server health
- Configure server settings and environment
Go to Team in the left navigation and click Add Employee. For each team member you'll provide:
- Full name and email address
- Department and job title
- Role: Employee, Manager, or Admin
Role permissions
| Role | Can Do |
|---|---|
| Employee | Access all modules, view team directory, manage own profile and notes |
| Manager | All of the above + view team usage reports, approve requests, access audit log |
| Admin | All of the above + manage users, billing, feature flags, server configuration |
Bulk import via seed data
For larger teams, use the seed CLI to import employees from a JSON file:
# Run inside the workapp container
docker compose exec workapp \
./workspace seed --db workspace --domain healthcareWorkSpace runs a fully self-hosted email stack - SMTP (port 25/587) and IMAP (port 993). No Gmail or Microsoft 365 dependency. Your organisation owns all mail data.
DNS records required
Add these records in your DNS provider (e.g. Namecheap, Cloudflare, GoDaddy) before sending email:
| Type | Host | Value | Purpose |
|---|---|---|---|
| A | your-server-ip | Mail server hostname | |
| MX | @ | mail.yourdomain.com (priority 10) | Inbound email routing |
| TXT | @ | v=spf1 ip4:your-server-ip ~all | Sender Policy Framework (spam prevention) |
| TXT | karyo._domainkey | (from admin panel → Email → DKIM) | DKIM signing (delivery authentication) |
| TXT | _dmarc | v=DMARC1; p=none; adkim=r; aspf=r | DMARC policy |
Verify email delivery
After DNS propagates (5–30 minutes), send a test email from the WorkSpace UI:
- Go to Email in the navigation
- Click Compose and send to an external address (e.g. Gmail)
- Check the received email shows DKIM=pass and SPF=pass in the headers
SMTP_RELAY_HOST=smtp.brevo.com in your .env file. This ensures deliverability while your domain builds reputation.WorkSpace's AI assistant answers questions about your org's data - emails, incidents, projects, knowledge base - using Retrieval Augmented Generation (RAG). It works with any of three LLM backends:
| Provider | Model | Speed | Privacy | Cost |
|---|---|---|---|---|
| Groq | llama-3.3-70b-versatile | Fastest (~1s) | Cloud (US) | Free tier generous |
| Gemini | gemini-2.0-flash | Fast (~2s) | Cloud (Google) | Free tier available |
| Ollama | gemma3:1b, phi4-mini | Slow (CPU-only) | Fully local | Free, runs on-device |
Option A - Groq (recommended)
Get a free API key at console.groq.com, then add it to your .env:
LLM_PROVIDER=groq
LLM_MODEL=llama-3.3-70b-versatile
GROQ_API_KEY=gsk_your_key_hereOption B - Ollama (fully local, no data leaves your server)
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Pull a fast model (gemma3:1b = ~1GB, ~8s warm inference)
ollama pull gemma3:1b
# Then set in .env:
LLM_PROVIDER=ollama
LLM_MODEL=gemma3:1b
OLLAMA_BASE_URL=http://localhost:11434After changing .env - restart the app
# Changes to .env require a full container recreate (not just restart)
docker compose stop workapp
docker compose rm -f workapp
docker compose up -d workappdocker compose restart does not re-read the --env-file. You must stop, remove, and recreate the container for environment variable changes to take effect.You're live
WorkSpace is fully set up. Here's a quick checklist to confirm everything is working before inviting your team:
- Health check passes:
curl http://localhost:8080/health→{"status":"ok"} - Admin login works at your domain
- HTTPS is configured (see SSL section below)
- Test email sent and received successfully
- AI assistant responds to a query in the Home page
- At least one team member added
Environment Variables Reference
All configuration lives in your ~/workspace/.env file. After editing, recreate the container to apply changes.
Core
| Variable | Description |
|---|---|
| APP_ENV required | Set to production to enable TLS enforcement, HSTS, and production log levels |
| APP_BASE_URL required | Full public URL, e.g. https://workspace.acme.com. Used in email links and OAuth callbacks |
| ADMIN_USERS required | Comma-separated admin email addresses, e.g. alice@acme.com,bob@acme.com |
| SESSION_STORE_KEY required | 32-byte base64 secret for session encryption. Auto-generated by install.sh. Never share this. |
Authentication
| Variable | Description |
|---|---|
| OKTA_ISSUER optional | Your Okta issuer URL, e.g. https://dev-123.okta.com/oauth2/default |
| OKTA_CLIENT_ID optional | Okta application Client ID |
| OKTA_CLIENT_SECRET optional | Okta application Client Secret |
| OKTA_REDIRECT_URI optional | Must match Okta app setting: https://your-domain.com/callback |
AI / LLM
| Variable | Description |
|---|---|
| LLM_PROVIDER optional | groq, gemini, or ollama. Defaults to groq. |
| LLM_MODEL optional | Model name for the chosen provider. Defaults: Groq → llama-3.3-70b-versatile, Ollama → gemma3:1b |
| GROQ_API_KEY optional | Required when LLM_PROVIDER=groq. Free at console.groq.com |
| OLLAMA_BASE_URL optional | Ollama server URL. Defaults to http://localhost:11434 |
MongoDB
| Variable | Description |
|---|---|
| MONGO_URI required | Full MongoDB connection string. Auto-generated by install.sh using the generated passwords. |
| MONGO_DATABASE optional | Database name. Defaults to workspace. |
Reverse Proxy (nginx)
WorkSpace runs on port 8080 internally. Use nginx as a reverse proxy to handle HTTPS on port 443 and redirect HTTP → HTTPS.
server {
server_name workspace.acme.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
}
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/workspace.acme.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/workspace.acme.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
}
server {
listen 80;
server_name workspace.acme.com;
return 301 https://$host$request_uri;
}SSL / HTTPS with Let's Encrypt
Let's Encrypt provides free 90-day SSL certificates with automatic renewal. This is the recommended approach.
# Install certbot
sudo apt install certbot python3-certbot-nginx -y
# Issue cert and auto-configure nginx
sudo certbot --nginx -d workspace.acme.com
# Verify auto-renewal
sudo certbot renew --dry-runKeeping WorkSpace Updated
# Pull latest images and restart (typically <60s downtime)
cd ~/workspace
docker compose pull
docker compose up -d
# View changelog after update
docker compose logs workapp | head -20.env file and MongoDB data are stored on Docker volumes - they persist across updates. The update process only replaces the application container.