Skip to content

Development Environment Setup

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)

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 Settings
DEBUG=True
SECRET_KEY=your-secret-key-here-change-in-production
ALLOWED_HOSTS=localhost,127.0.0.1

# Database Configuration
DATABASE_URL=postgresql://arctyk_user:arctyk_password@db:5432/arctyk_db

# Redis Configuration
REDIS_URL=redis://redis:6379/0

# Email Configuration (for local development)
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

# Celery Configuration
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

# Security (Development only - change for production)
SECURE_SSL_REDIRECT=False
SESSION_COOKIE_SECURE=False
CSRF_COOKIE_SECURE=False

Security

Never commit your .env file to version control. It's already in .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

Create the database schema:

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

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

Step 5: Create a Superuser

Create an admin account to access the Django admin:

docker-compose exec web python manage.py createsuperuser

# Follow the prompts:
# Username: admin
# Email address: admin@example.com
# Password: (enter a secure password)

Step 6: Load Sample Data (Optional)

Load sample tickets and projects for testing:

# Load fixtures
docker-compose exec web python manage.py loaddata sample_data

# Or create your own test data through the admin interface

Step 7: Access the Application

The application should now be running:

Log in with the superuser credentials you created.

Step 8: Verify Everything Works

Test Ticket Creation

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

Check Celery Tasks

# View Celery worker logs
docker-compose logs celery

# Should show worker is ready

Run Tests

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

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

# Run with coverage
docker-compose exec web coverage run --source='.' 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 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 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 manage.py makemigrations

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

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

Debugging

# Django shell
docker-compose exec web python manage.py shell

# Database shell
docker-compose exec web python 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: