Get Started

ITDocs runs as a set of Docker containers. You’ll have a fully working instance in under 10 minutes.

What you’ll need

🐳
Docker + Compose
Install Docker · Install Compose
🌐
Domain or local IP
Optional, but recommended for public access
🔓
Open ports
Port 443 for public, or local IP for internal use

1 Create your project folder

mkdir itdocs && cd itdocs

2 Create your docker-compose.yml

Create a file called docker-compose.yml in your project folder and paste the following:

services:
  web:
    image: jharlan1980/itdocs-web:latest
    container_name: itdocs-web
    restart: unless-stopped
    ports:
      - "443:443"
    depends_on:
      - api
    networks:
      - itdocs

  api:
    image: jharlan1980/itdocs-api:latest
    container_name: itdocs-api
    restart: unless-stopped
    env_file: .env
    expose:
      - "4000"
    volumes:
      - backup_data:/var/backups/itdocs
      - files_backup_data:/var/backups/itdocs-files
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - itdocs

  postgres:
    image: postgres:16-alpine
    container_name: itdocs-postgres
    restart: unless-stopped
    env_file: .env
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - itdocs

  redis:
    image: redis:7-alpine
    container_name: itdocs-redis
    restart: unless-stopped
    command: >
      redis-server
      --requirepass ${REDIS_PASSWORD}
      --appendonly yes
      --appendfsync everysec
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - itdocs

volumes:
  postgres_data:
  redis_data:
  backup_data:
  files_backup_data:

networks:
  itdocs:
    driver: bridge

3 Create your .env file

Create a .env file in the same folder. This is where all your configuration lives.

# Database
POSTGRES_USER=itdocs
POSTGRES_PASSWORD=your_secure_db_password
POSTGRES_DB=itdocs
DATABASE_URL=postgresql://itdocs:your_secure_db_password@postgres:5432/itdocs?schema=public

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your_secure_redis_password

# API Security
JWT_SECRET=generate_a_random_secret_string

# Must be exactly 64 hexadecimal characters! (Run: openssl rand -hex 32)
VAULT_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
CORS_ORIGIN=*

# (Optional) - Data backup and exports
BACKUP_PATH=/var/backups/itdocs
BACKUP_PASSWORD=your_secure_backups_password
BACKUP_FILES_PATH=/var/backups/itdocs-files

FRONTEND_URL=https://www.dragonflare.us/

Generate your secrets

Run these two commands to generate secure values for JWT_SECRET and VAULT_ENCRYPTION_KEY:

# JWT_SECRET (32 random bytes as base64)
openssl rand -base64 32

# VAULT_ENCRYPTION_KEY (must be exactly 64 hex chars)
openssl rand -hex 32

Paste the output directly into your .env file.

⚠️

Keep your .env file secure. Never commit it to version control. The VAULT_ENCRYPTION_KEY encrypts all stored passwords — if you lose it, vault entries cannot be recovered.

4 Start ITDocs

docker compose up -d

Docker will pull the images and start all four containers. The first run may take a minute or two. Verify everything is running:

docker compose ps
ℹ️

You should see itdocs-web, itdocs-api, itdocs-postgres, and itdocs-redis all with a status of running. If any container has exited, run docker compose logs itdocs-api to diagnose.

5 First login

Open your browser and navigate to your server’s IP or hostname.

⚠️

Change the default password immediately. A default admin account is created automatically when the container first starts.

  1. Navigate to your instance in the browser
  2. Log in with the default credentials:
    Email: [email protected]
    Password: ChangeMe123!
  3. Go to Settings → Users and update the password immediately
  4. Optionally update the email address to your own

Additional user accounts can be created by an ADMIN from Settings → Users.

6 Initial setup

Once logged in as ADMIN, head to Settings and configure the basics:

  • General — upload your company logo, set your instance name
  • Users — Setup SSO with Microsoft or Google, Connect your ldap/active directory or create local accounts for your team, assign roles (ADMIN / TECHNICIAN / VIEWER)
  • MFA — MFA can be enabled for local accounts
  • Integrations — optionally connect ConnectWise Manage or NinjaRMM for auto-sync
  • RustDesk — optionally enable remote access enrollment for Windows machines

That’s it — ITDocs is ready to use.

Environment variables reference

VariableRequiredDescription
DATABASE_URL✅Full PostgreSQL connection string
POSTGRES_PASSWORD✅Password for the Postgres container (must match the one in DATABASE_URL)
REDIS_HOST✅Redis hostname — use redis when running via Docker Compose
REDIS_PORT—Redis port (default: 6379)
REDIS_PASSWORD✅Redis password
JWT_SECRET✅Minimum 32 characters. Signs all access tokens
VAULT_ENCRYPTION_KEY✅Exactly 64 hex characters (32 bytes). Encrypts all vault passwords. Do not change after data is stored
FRONTEND_URL—Full URL of your instance — used for SSO redirects
CORS_ORIGIN—Allowed CORS origin — should match FRONTEND_URL
PORT—API port inside the container (default: 4000)
HOST—Bind address (default: 0.0.0.0)
LOG_LEVEL—Pino log level: trace debug info warn error (default: info)
BACKUP_PATH—Server path for scheduled encrypted DB backups
BACKUP_PASSWORD—Password used to encrypt DB backup archives (min 8 chars)
BACKUP_FILES_PATH—Server path for incremental file/attachment backups

Troubleshooting

Containers won’t start▶

Run docker compose logs itdocs-api to see the API logs. Most startup failures are caused by missing or malformed .env values — check that all required variables are set and have no extra spaces or quotes.

Can’t reach the app in the browser▶

Check that port 443 is open on your firewall and that the itdocs-web container is running (docker compose ps). If you’re behind a reverse proxy, make sure it’s forwarding to the correct port.

Forgot the admin password▶

Log in with the default credentials ([email protected] / ChangeMe123!) if you haven’t changed them yet. Otherwise have another ADMIN reset it from Settings → Users, or connect directly to the Postgres container and update the users table with a new bcrypt-hashed password.

VAULT_ENCRYPTION_KEY warning or vault entries not decrypting▶

If you change VAULT_ENCRYPTION_KEY after passwords have been stored, existing vault entries will fail to decrypt. Treat this key like a master password — back it up somewhere safe and never rotate it unless you have a migration plan.