Skip to content

Installation Guide (Docker)

This guide explains how to set up a local development version of Arctyk ITSM using Docker and Docker Compose.

By the end of this procedure, you’ll have the application running locally with a Postgres database.

Prerequisites

Make sure the following are installed on your system:

git clone https://github.com/Arctyk-ITSM/arctyk-itsm.git
cd arctyk

Project Structure

Your repo should look similar to this:

arctyk/
├── .gitignore
├── .dockerignore
├── Dockerfile
├── docker-compose.yml
├── .env
├── requirements.in
├── requirements.txt
├── dev-requirements.in
├── dev-requirements.txt
├── .flake8
├── .pre-commit-config.yaml
├── entrypoint.sh
├── package.json
├── pyproject.toml  
├── STATIC_SRC/
│ ├── bootstrap-icons/
│ ├── scss/
│ └── css/
│ └── js/
│ └── images/
└── static/
├── src/
│ ├── manage.py
│ ├── config/
│ ├── core/
│ ├── fixtures/
│ ├── tickets/
│ ├── users/
│ ├── projects/
│ ├── inventory/
│ └── reports/
├── media/

Environment Variables

Create a .env file in the project root:

# Django
DJANGO_SECRET_KEY=super-secret-key
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=*

# Database
POSTGRES_DB=arctyk
POSTGRES_USER=arctyk
POSTGRES_PASSWORD=arctyk
POSTGRES_HOST=db
POSTGRES_PORT=5432

# Static / Media
STATIC_ROOT=/code/static
MEDIA_ROOT=/code/media

Docker Compose File

Example docker-compose.yml:

version: "3.9"

services:
  db:
    image: postgres:17
    restart: always
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "5433:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  web:
    build:
      context: .
      dockerfile: Dockerfile
    command: >
      sh -c "python src/manage.py migrate &&
              python src/manage.py collectstatic --noinput &&
              gunicorn helpdesk.asgi:application -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000"
    volumes:
      - .:/code
    env_file: .env
    ports:
      - "8000:8000"
    depends_on:
      - db

volumes:
  postgres_data:

Dockerfile for Web

In Dockefile:

# Use a slim Python base
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1 \
      PYTHONDONTWRITEBYTECODE=1

WORKDIR /code

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential libpq-dev libjpeg-dev zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

Build and Run

Build and start containers:

docker compose up -d --build

Check logs:

docker compose logs -f

Automatic Admin User

Arctyk ITSM automatically creates a default superuser/admin account the first time the app starts if one does not already exist.

  • Username: admin
  • Pasword: adminpass
  • Email: admin@example.com

Database Setup

Once the containers are running, run migrations:

docker compose exec web python src/manage.py migrate

Create a superuser:

docker compose exec web python src/manage.py createsuperuser

Access the App

First-Run Data Setup

(Optional) Load fixtures or auto-create data like HelpdeskSettings:

docker compose exec web python sr/manage.py loaddata initial_data.json

Stopping & Restarting

docker compose down # stop
docker compuse up -d  # restart

That's It!

You should now have a fully running Arctyk ITSM instance inside Docker.

Next Steps

Once configuration is complete, proceed to: