Local Development

This guide helps you set up a local development environment for the IDK project.

Table of Contents

  1. Requirements
  2. Initial Setup
  3. Development with Docker (recommended)
  4. Debugging
  5. Using Cursor/VS Code
  6. Manual Setup (without Docker)
  7. Frontend Development
  8. Reports & WebSockets
  9. Webhooks (ClickUp)
  10. Testing
  11. CI/CD (overview)
  12. Deployment (overview)
  13. Troubleshooting

1) Requirements

  • Python 3.11+
  • Node.js 18+
  • PostgreSQL 12+
  • Redis 6+
  • Docker or OrbStack
  • Git

2) Initial Setup

Clone the repository and configure environment variables.

git clone git@github.com:swappsco/idk.git
cd idk

# Prepare env file
cp env.example .env
# Edit .env with your local settings (DB, Redis, external APIs)

# Avoid committing changes to env.example
git update-index --assume-unchanged env.example
# Build image
make build

# Start the stack
make run-local

# Open a shell in the container
make ssh-local

# Apply migrations
python manage.py migrate

# Run server
python manage.py runserver 0.0.0.0:8000

Stop services:

make stop-local

4) Debugging

Run Django with debugpy and attach a debugger:

python -m debugpy --listen 0.0.0.0:3001 manage.py runserver 0.0.0.0:8000

Attach from Cursor/VS Code with the "Python: Attach" configuration.

5) Using Cursor/VS Code

  • Attach to container using Dev Containers / Remote Explorer
  • The repo includes .vscode/settings.json enabling pytest discovery:
{
  "python.testing.unittestEnabled": false,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["/app/idk"]
}

Recommended extensions: Python, Pylance, Python Test Explorer.

6) Manual Setup (without Docker)

# Create venv (example using virtualenvwrapper)
mkvirtualenv idk -p python3
workon idk

# Python deps
pip install -r requirements/local.txt

# Node deps
yarn install

# Build assets (or use watch for dev)
yarn run build
# or
yarn run watch

7) Frontend Development

  • Vue-based UI; assets are built via Webpack.
  • For development with hot reload:
yarn run watch

8) Reports & WebSockets

Real-time reporting uses WebSockets via Django Channels. Key consumers live under idk/api/consumers.py and idk/notifications/consumers.py.

Typical patterns:

# WebSocket URL example
ws/company/total-report/{company_uuid}/

# Date range helpers
first_date, second_date, month, year = get_dates_from_url(request)

Guidelines: - Cache frequently accessed data - Optimize queries and add indexes - Use update() for pushing real-time updates

9) Webhooks (ClickUp)

Expose your local server via ngrok and register webhooks:

ngrok http 8000

Management command:

python manage.py manage_clickup_webhooks

Required events include: taskStatusUpdated, taskCreated, taskUpdated, taskDeleted, folderDeleted, taskTimeTrackedUpdated.

10) Testing

Python tests:

python manage.py test

# with coverage
coverage run manage.py test
coverage report -m

JavaScript tests:

yarn test

Pytest discovery is configured in pytest.ini (see testpaths).

11) CI/CD (overview)

GitHub Actions workflows are under .github/workflows/ and include: - Build and test pipelines (Python + Node) - Docker image build and push to GHCR - Optional quality checks (SonarQube)

Docs deployment (MkDocs) runs on push to master or manual trigger.

12) Deployment (overview)

Deployments are managed in a separate repo and synchronized via Argo CD: 1. CI builds and pushes a Docker image (ghcr.io/swappsco/idk:<tag>) 2. Update the deploy repo to reference the new image tag 3. Argo CD syncs changes to environments

13) Troubleshooting

  • Docker build fails: update Docker/Compose, check disk space, docker system prune
  • DB connection issues: verify Postgres is running, .env credentials, permissions
  • Frontend build fails: clear node_modules, yarn cache clean, reinstall deps