Skip to content

Development Environment Setup

Version: Arctyk ITSM v0.6.0+
Last Updated: January 2026

This guide walks you through setting up a complete local development environment for Arctyk ITSM.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

  • Visual Studio Code - Download VS Code
  • PostgreSQL client - For database inspection (e.g., pgAdmin, DBeaver)
  • Redis client - For cache/queue inspection (e.g., Redis Commander)
  • Bash terminal - For executing docker compose and other build commands

Step 1: Clone the Repository

# Clone the repository
git clone https://github.com/Arctyk-ITSM/arctyk-itsm.git

# Navigate to the project directory
cd arctyk-itsm

Step 2: Environment Configuration

Create a .env file in the project root with the following configuration:

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

Edit .env with your preferred settings:

# ──────────────── Django App Settings ────────────────

DEBUG=False
DJANGO_ALLOWED_HOSTS=localhost 127.0.0.1 [::1]  # Add your domain or public IP for production

# ──────────────── Secret Key ────────────────
# IMPORTANT: Replace with a secure key in .env (do not use this template key)
SECRET_KEY=changeme-in-real-env

# ──────────────── Django Superuser (Auto Create) ────────────────
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@example.com
DJANGO_SUPERUSER_PASSWORD=admin123  # Change in real .env

# ──────────────── PostgreSQL Settings ────────────────
POSTGRES_DB=helpdesk
POSTGRES_USER=postgres    # Change or leave default
POSTGRES_PASSWORD=changeme123  # Change in real .env
POSTGRES_HOST=db
POSTGRES_PORT=5432

# ──────────────── Redis / Celery (Optional) ────────────────
REDIS_URL=redis://redis:6379/0

Security

Never commit your .env file to version control. Ensure it's added to .gitignore.

Step 3: Start Docker Services

Arctyk ITSM uses Docker Compose for local development. This starts PostgreSQL, Redis, and the Django development server.

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop services when done
docker compose down

The docker compose.yml includes:

  • db - PostgreSQL 15 database
  • redis - Redis for caching and Celery
  • web - Django development server
  • celery - Celery worker for background tasks

Step 4: Run Database Migrations

Warning

I recommend you skip this step and move directly to Step 5. Running database migrations at this stage may cause errors which will break the build.

Create the database schema:

# Run migrations
docker compose exec web python src/manage.py migrate

# You should see output like:
# Running migrations:
#   Applying contenttypes.0001_initial... OK
#   Applying auth.0001_initial... OK
#   ...

Step 5: Launch the App

  1. Open http://localhost:8000 in a web browser:
  2. Log in using the default credentials:
    • Username: admin
    • Password: admin123

Step 6: Verify Everything Works

Test Ticket Creation

  1. Navigate to the tickets page
  2. Click "Create Ticket"
  3. Fill in the ticket form and submit
  4. Verify the ticket appears in the list

Check Celery Tasks (Optional)

# View Celery worker logs
docker compose logs celery

# Should show worker is ready

Run Tests (Optional)

# Run the full test suite
docker compose exec web python src/manage.py test

# Run specific app tests
docker compose exec web python src/manage.py test tickets

# Run with coverage
docker compose exec web coverage run --source='.' src/manage.py test
docker compose exec web coverage report

Common Troubleshooting

Database Connection Issues

# Ensure database is running
docker compose ps

# Restart database service
docker compose restart db

# Check database logs
docker compose logs db

Static Files Not Loading

# Collect static files
docker compose exec web python src/manage.py collectstatic --noinput

# Or rebuild SCSS
docker compose exec web npm run build:scss

Port Already in Use

# Change port in docker-compose.yml
# Update ports section for web service:
ports:
  - "8001:8000"  # Changed from 8000:8000

Migrations Out of Sync

# Reset migrations (WARNING: destroys data)
docker compose down -v
docker compose up -d
docker compose exec web python src/manage.py migrate

Development Workflow

Making Code Changes

  1. Make changes to Python, HTML, or SCSS files
  2. Django auto-reloads on Python changes
  3. For SCSS changes, run: npm run build:scss
  4. Refresh browser to see changes

Working with Migrations

# Create new migration
docker compose exec web python src/manage.py makemigrations

# Apply migrations
docker compose exec web python src/manage.py migrate

# View migration SQL
docker compose exec web python src/manage.py sqlmigrate tickets 0001

Debugging

# Django shell
docker compose exec web python src/manage.py shell

# Database shell
docker compose exec web python src/manage.py dbshell

# View logs
docker compose logs -f web

IDE Setup

Visual Studio Code

Install recommended extensions:

  • Python (Microsoft)
  • Django (Baptiste Darthenay)
  • Pylance (Microsoft)
  • GitLens (GitKraken)
  • Docker (Microsoft)

Add to .vscode/settings.json:

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.python"
  }
}

Next Steps

Now that your environment is set up:

  1. Read the architecture overview
  2. Review coding standards
  3. Make your first contribution
  4. Explore the developer guide

Getting Help

If you encounter issues: