Installation

Complete development environment setup for Vulcan.

System Requirements

Required Tools

Tool	Version	Purpose
Git	2.30+	Version control
Docker	24+	Container runtime
Docker Compose	2.20+	Multi-container orchestration
Node.js	20 LTS	Frontend development
.NET SDK	10.0	Backend development
Make	Any	Workspace commands

Recommended Tools

Tool	Purpose
VS Code	IDE with extensions
Rider	.NET IDE alternative
Postman / Bruno	API testing
pgAdmin / DBeaver	Database management

Installation Steps

1. Install Prerequisites

macOS

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install tools
brew install git node@20 docker docker-compose
brew install --cask dotnet-sdk

# Verify installations
git --version
node --version
dotnet --version
docker --version

Ubuntu/Debian

# Update package list
sudo apt update

# Install Git and Node.js
sudo apt install git
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Install .NET 10
wget https://dot.net/v1/dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 10.0

Windows

# Using winget
winget install Git.Git
winget install OpenJS.NodeJS.LTS
winget install Microsoft.DotNet.SDK.10
winget install Docker.DockerDesktop

# Verify installations
git --version
node --version
dotnet --version
docker --version

2. Configure Git

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Generate SSH key (if needed)
ssh-keygen -t ed25519 -C "your.email@example.com"

# Add to GitLab
cat ~/.ssh/id_ed25519.pub
# Copy and add to GitLab > Settings > SSH Keys

3. Clone the Workspace

# Clone with submodules
git clone --recursive git@gitlab.hantverksdata.se:vulcan/vulcan-workspace.git
cd vulcan-workspace

# Initialize (installs dependencies)
make init

4. Start Services

# Start databases and infrastructure
make dev

# Verify services are running
make ps

5. Run the Application

# Terminal 1: Frontend
make dev-web

# Terminal 2: Backend (choose a capability)
make dev-be CAP=coresetup

VS Code Setup

Recommended Extensions

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "ms-dotnettools.csharp",
    "ms-dotnettools.csdevkit",
    "formulahendry.dotnet-test-explorer",
    "humao.rest-client",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens"
  ]
}

Settings

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[csharp]": {
    "editor.defaultFormatter": "ms-dotnettools.csharp"
  },
  "typescript.preferences.importModuleSpecifier": "relative"
}

Troubleshooting

Docker Issues

# Reset Docker if containers won't start
make clean
docker system prune -a
make dev

Port Conflicts

If a port is already in use:

# Find what's using the port
lsof -i :5432

# Kill the process
kill -9 <PID>

Submodule Issues

# Reset submodules
git submodule deinit -f .
git submodule update --init --recursive

Next Steps

• Read the Architecture Overview
• Understand Development Conventions
• Explore the API Reference