Modern Docker Management, Designed for Everyone
Contributing to Arcane
Thanks for helping make Arcane better! We've built a modern, streamlined development experience that gets you up and running in minutes.
Using AI tools? Please read our AI Usage Policy before contributing.
π Ways to Contribute
- π Report bugs using our issue templates
- π‘ Suggest features in Discussions. Proposals and voting belong there. Maintainers can create linked implementation issues when work is ready.
- π§ Code contributions (frontend, backend, DevOps)
- π Documentation improvements
- π Translations via Crowdin
- π§ͺ Testing and quality assurance
π Quick Start
Prerequisites
- Docker & Docker Compose
- VS Code based IDE (recommended for the best developer experience)
- Vite+ (
curl -fsSL https://vite.plus | bash). - golangci-lint v2 β runs Go linting and formatting.
π‘ Working Directory: Unless otherwise specified, all commands in this guide should be run from the project root directory (
arcane/).
1. Fork and Clone
git clone https://github.com/<your-username>/arcane.git
cd arcane
2. Start Development Environment
From the project root directory:
./scripts/development/dev.sh start
That's it! The development environment will automatically:
- π₯ Start both frontend and backend with hot reload
- π³ Handle all dependencies via Docker
- π Set up health checks and monitoring
- πΎ Create persistent storage for your development data
Access your development environment:
- Frontend: http://localhost:3000 (SvelteKit with HMR)
- Backend: http://localhost:3552 (Go with Air hot reload)
π― VS Code Integration
For the best development experience, we've included VS Code tasks and workspace configuration.
Recommended Extensions
When you open the project in VS Code, you'll be prompted to install our recommended extensions. These provide:
- Docker integration and management
- Go language support with debugging
- Svelte/TypeScript support
- Integrated terminal management
One-Click Development Commands
Use Ctrl/Cmd+Shift+P β "Tasks: Run Task" to access:
| Task | Description |
|---|---|
| Start | Start the development environment |
| Stop | Stop all services |
| Restart | Restart all services |
| Rebuild | Rebuild containers (after dependency changes) |
| Clean | Remove all containers and volumes |
| Logs | Interactive log viewer with service selection |
| Open Frontend | Launch frontend in browser |
Quick Build Shortcut
Press Ctrl/Cmd+Shift+B to run the default build task (Start Environment).
π Development Workflow
Making Changes
Create a feature branch:
git switch -c feat/my-awesome-feature # or git switch -c fix/issue-123Start development (from project root):
./scripts/development/dev.sh start # or use VS Code Task: "Start"Monitor logs (choose your preferred method):
# Interactive selector ./scripts/development/dev.sh logs # Specific service ./scripts/development/dev.sh logs frontend ./scripts/development/dev.sh logs backend # Or use VS Code Task: "Logs"Make your changes - hot reload will automatically update:
- Frontend: Instant HMR via Vite
- Backend: Auto-rebuild and restart via Air
π οΈ Development Commands
Note: All commands should be run from the project root directory (arcane/).
Justfile Shortcuts
We provide a categorized Justfile for common workflows. Run just --list to see every category and target.
# Development
just dev docker
just dev logs
# Build
just build single frontend
just build single backend
# Tests
just test all
just test backend
# Quality checks
just lint frontend
just format frontend
just format all --check
# Dependencies
just deps install all
Environment Management
# Start development environment
./scripts/development/dev.sh start
# View service status
./scripts/development/dev.sh status
# Stop all services
./scripts/development/dev.sh stop
# Restart services (for config changes)
./scripts/development/dev.sh restart
# Rebuild containers (for dependency changes)
./scripts/development/dev.sh rebuild
# Clean up everything (nuclear option)
./scripts/development/dev.sh clean
Debugging & Logs
# Interactive log selection
./scripts/development/dev.sh logs
# All services
./scripts/development/dev.sh logs
# Frontend only (Vite/SvelteKit)
./scripts/development/dev.sh logs frontend
# Backend only (Go/Air)
./scripts/development/dev.sh logs backend
# Shell access
./scripts/development/dev.sh shell frontend
./scripts/development/dev.sh shell backend
π¨ Code Quality
Automatic Formatting & Linting
Both services include development-time linting and formatting:
- Frontend / TypeScript: Vite+ (
vp fmt,vp check) + Svelte/TypeScript checks β formatting and lint rules live in the rootvite.config.ts - Backend: Go fmt + Go vet (built into Air hot reload)
Pre-commit Hooks
Format checks run automatically on staged files via the Vite+ git hook dispatcher. Enable it once after cloning:
vp hooks enable
Manual Commands
If you need to run checks manually:
# JS/TS formatting and lint (Vite+, run from project root)
vp fmt --check
vp check
# Or via the Justfile
just format all --check
just lint js
# Inside the Docker dev environment
docker compose -f docker/compose.dev.yaml exec frontend pnpm check
docker compose -f docker/compose.dev.yaml exec frontend pnpm format
# Backend checks
docker compose -f docker/compose.dev.yaml exec backend go fmt ./...
docker compose -f docker/compose.dev.yaml exec backend go vet ./...
π Commit Guidelines
We use Conventional Commits for clear, semantic commit messages:
git commit -m "feat: add user authentication"
git commit -m "fix: resolve Docker volume mounting issue"
git commit -m "docs: update development setup guide"
git commit -m "refactor: simplify API response handling"
Types: feat, fix, docs, style, refactor, test, chore
π Pull Request Process
- Keep changes focused - One feature/fix per PR
- Test your changes - Ensure both frontend and backend work
- Update documentation - If you change APIs or add features
- Link issues - Reference issues with "Closes #123" or "Fixes #456"
- Be responsive - Address review feedback promptly
PR Checklist
- Code builds successfully in development environment
- Frontend hot reload works correctly
- Backend hot reload works correctly
- No linting errors
- Commit messages follow conventional format
- PR description explains the change and why it's needed
π Troubleshooting
Development startup checklist
When ./scripts/development/dev.sh start fails or the app does not load, validate the environment in this order before changing code:
Confirm Docker is installed and the daemon is reachable:
docker info docker compose versionConfirm the development compose file is valid from the project root:
docker compose -f docker/compose.dev.yaml -p arcane-dev configStart the stack and inspect container state:
./scripts/development/dev.sh start ./scripts/development/dev.sh statusCheck the expected development endpoints:
curl -f http://localhost:3000 curl -f http://localhost:3552/api/health curl -f http://localhost:3552/api/health/ready/api/healthreports process liveness./api/health/readyalso pings the database and Docker and returns 503 until both answer; use it for orchestrator readiness probes if you need one.If a service is unhealthy, read the targeted logs first:
./scripts/development/dev.sh logs frontend ./scripts/development/dev.sh logs backend
Common Issues
Port conflicts:
# Stop and clean everything (from project root)
./scripts/development/dev.sh clean
# Check for conflicting processes
lsof -i :3000 # Frontend port
lsof -i :3552 # Backend port
Docker issues:
# Reset Docker environment (from project root)
./scripts/development/dev.sh clean
docker system prune -f
# Restart development
./scripts/development/dev.sh start
VS Code tasks not working:
- Ensure you've opened the project root folder (
arcane/) in VS Code, not a subfolder or parent directory - Install recommended extensions when prompted
- Restart VS Code if tasks don't appear
- Verify you're in the correct working directory when running terminal commands
Need Help?
- Bug Report: Create an issue
- Feature Request: Suggest a feature (Discussions)
- Development Question: Open a discussion in the repository
Thank you for contributing to Arcane! Your help makes this project better for everyone. π