Local Development Setup

This guide is for contributors and developers who want to run DeployStack locally for development purposes. If you want to deploy DeployStack for production use, see our Self-Hosted Documentation.

For production deployments, use our Docker Compose setup instead.

Prerequisites

# Before you can install and use DeployStack locally, make sure you have:
# - Git: Version control system
# - Node.js v18+: JavaScript runtime (v18 or higher required)
# - npm v8+: Package manager (comes with Node.js)
# - Docker: For running PostgreSQL database

# Verify Installation
git --version
node --version  # Should be v18 or higher
npm --version   # Should be v8 or higher
docker --version

# For Windows development, we recommend using WSL2
# 1. Install WSL2: Follow Microsoft's WSL installation guide
# 2. Install Ubuntu: From Microsoft Store or command line
# 3. Install development tools in WSL:

# Update package list
sudo apt update

# Install Git
sudo apt install git

# Install Node.js v18 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

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

# Verify Installation
git --version
node --version  # Should be v18 or higher
npm --version   # Should be v8 or higher
docker --version

Windows (WSL) Users: After installing Docker, you may need to restart your WSL session or run newgrp docker to use Docker without sudo.

Step 1: Clone the Repository

# If you haven't set up SSH keys, learn how at:
# https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh

git clone git@github.com:deploystackio/deploystack.git
cd deploystack

git clone https://github.com/deploystackio/deploystack.git
cd deploystack

Step 2: Install Dependencies

Install all project dependencies using npm workspaces:

# Install dependencies for all services
npm install

DeployStack uses npm workspaces to manage dependencies across frontend and backend services. The root npm install will install dependencies for all services.

Step 3: Set Up Environment Variables

Backend Environment

Create the backend environment file:

# Create backend .env file
cp services/backend/.env.example services/backend/.env

Edit services/backend/.env with your configuration:

# Required: Generate a secure encryption secret
DEPLOYSTACK_ENCRYPTION_SECRET=your-32-character-secret-here

# Frontend URL (for CORS and redirects)
DEPLOYSTACK_FRONTEND_URL=http://localhost:5173

# PostgreSQL Configuration (matches postgres:local defaults)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=deploystack
POSTGRES_USER=deploystack
POSTGRES_PASSWORD=deploystack
POSTGRES_SSL=false

# Development settings
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

Frontend Environment

Create the frontend environment file:

# Create frontend .env file
cp services/frontend/.env.example services/frontend/.env

Edit services/frontend/.env with your configuration:

# Backend API URL
VITE_DEPLOYSTACK_BACKEND_URL=http://localhost:3000

# App configuration
VITE_APP_TITLE=DeployStack (Dev)

Generate Encryption Secret

# Using OpenSSL (recommended)
openssl rand -hex 16

# Alternative using Node.js
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

# Using PowerShell
-join ((1..32) | ForEach {'{0:X}' -f (Get-Random -Max 16)})

# Using Node.js (if available)
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

Step 4: Start PostgreSQL Database

DeployStack uses PostgreSQL as its database backend. For local development, we provide a convenient script to start PostgreSQL in Docker:

# Start PostgreSQL 18 in Docker
npm run postgres:local

This command will:

Pull PostgreSQL 18 Docker image
Create a local PostgreSQL container with default credentials:
- Host: localhost
- Port: 5432
- Database: deploystack
- User: deploystack
- Password: deploystack
Create a persistent volume for database data

The PostgreSQL container will persist data between restarts. To reset the database, remove the postgres_data volume: docker volume rm postgres_data

Verify PostgreSQL is Running

# Check if PostgreSQL container is running
docker ps | grep postgres-local

# Test connection
psql -h localhost -U deploystack -d deploystack -c "SELECT version();"

Step 5: Running the Development Servers

DeployStack requires both frontend and backend services to run simultaneously.

Option 1: Separate Terminals (Recommended)

Run each service in its own terminal for better log visibility:

# Terminal 1: Start backend server
npm run dev:backend

# Terminal 2: Start frontend server (in a new terminal)
npm run dev:frontend

Option 2: Background Processes

Run both services from a single terminal:

# Start backend in background
npm run dev:backend &

# Start frontend
npm run dev:frontend

# To stop background processes later:
# pkill -f "npm run dev:backend"

# Start backend in new window
Start-Process powershell -ArgumentList "-NoExit", "-Command", "npm run dev:backend"

# Start frontend in current window
npm run dev:frontend

Development URLs

Once both services are running:

Frontend: http://localhost:5173 (Vite dev server)
Backend API: http://localhost:3000 (Fastify server)
API Documentation: http://localhost:3000/documentation (Swagger UI)

Step 6: Verify Installation

Check Service Status

Verify both services are running:

# Check if ports are listening
curl http://localhost:3000/health  # Backend health check
curl http://localhost:5173         # Frontend dev server

Access the Application

Open http://localhost:5173 in your browser. You should see the DeployStack interface.

Complete Setup Wizard

Follow the on-screen setup wizard to:

Configure PostgreSQL database connection
Create your first admin user
Set up basic platform settings

Development Workflow

Hot Reloading

Both services support hot reloading:

Frontend: Vite automatically reloads on file changes
Backend: Nodemon restarts the server on file changes

Available Scripts

From the project root:

# Database
npm run postgres:local        # Start PostgreSQL in Docker

# Development
npm run dev:frontend          # Start frontend dev server
npm run dev:backend           # Start backend dev server

# Building
npm run build:frontend        # Build frontend for production
npm run build:backend         # Build backend TypeScript

# Linting
npm run lint:frontend         # Lint frontend code
npm run lint:backend          # Lint backend code
npm run lint:md               # Lint markdown files

# Database Migrations
npm run db:generate           # Generate new migrations

# Testing
npm run test:backend:unit     # Run backend unit tests
npm run test:backend:e2e      # Run backend e2e tests
npm run test:backend:unit:coverage  # Run tests with coverage

# Releases
npm run release:frontend      # Create frontend release
npm run release:backend       # Create backend release

Project Structure

deploystack/
├── services/
│   ├── frontend/           # Vue.js frontend application
│   │   ├── src/           # Source code
│   │   ├── public/        # Static assets
│   │   ├── package.json   # Frontend dependencies
│   │   └── vite.config.ts # Vite configuration
│   ├── backend/           # Fastify backend API
│   │   ├── src/          # Source code
│   │   ├── tests/        # Test files
│   │   ├── persistent_data/ # Database and application data
│   │   ├── package.json  # Backend dependencies
│   │   └── tsconfig.json # TypeScript configuration
│   └── shared/           # Shared utilities and types
├── scripts/              # Build and deployment scripts
├── package.json          # Root package.json (workspaces)
└── docker-compose.yml    # Production deployment

Troubleshooting

Common Issues

Port Already in Use

# Check what's using the port
lsof -i :3000  # Backend port
lsof -i :5173  # Frontend port
lsof -i :5432  # PostgreSQL port

# Kill process using the port
kill -9 <PID>

Node Version Issues

# Check Node version
node --version

# If using nvm, switch to correct version
nvm install 18
nvm use 18

Permission Errors

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# Fix project permissions
sudo chown -R $(whoami) .

Run your terminal as Administrator or ensure you have write permissions to the project directory.

PostgreSQL Connection Issues

# Check if PostgreSQL container is running
docker ps | grep postgres-local

# View PostgreSQL logs
docker logs postgres-local

# Restart PostgreSQL
docker stop postgres-local
npm run postgres:local

# Reset PostgreSQL (removes all data)
docker stop postgres-local
docker rm postgres-local
docker volume rm postgres_data
npm run postgres:local

Environment Variable Issues

# Verify environment files exist
ls -la services/backend/.env
ls -la services/frontend/.env

# Check if encryption secret is set
grep DEPLOYSTACK_ENCRYPTION_SECRET services/backend/.env

# Check PostgreSQL configuration
grep POSTGRES services/backend/.env

Getting Help

If you encounter issues not covered here:

Check Logs: Look at the console output from both frontend and backend servers
Search Issues: Look for similar problems in GitHub Issues
Community Support: Ask for help in our Discord
Create Issue: Report bugs with detailed logs and system information

Contributing

Once you have DeployStack running locally:

Read Contributing Guidelines: Check CONTRIBUTING.md
Create Feature Branch: git checkout -b feature/amazing-feature
Make Changes: Implement your feature or bug fix
Test Changes: Run tests and verify functionality
Submit Pull Request: Create a PR with detailed description

Next Steps

Explore the Codebase: Familiarize yourself with the project structure
Read API Documentation: Check the backend API docs at http://localhost:3000/documentation
Join Development Discussions: Participate in our Discord development channels
Check Open Issues: Find issues to work on in our GitHub repository

Ready to contribute? Check our Contributing Guidelines to get started!

Guides

Administration

Prerequisites

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Environment Variables

Backend Environment

Frontend Environment

Generate Encryption Secret

Step 4: Start PostgreSQL Database

Verify PostgreSQL is Running

Step 5: Running the Development Servers

Option 1: Separate Terminals (Recommended)

Option 2: Background Processes

Development URLs

Step 6: Verify Installation

Development Workflow

Hot Reloading

Available Scripts

Project Structure

Troubleshooting

Common Issues

Port Already in Use

Node Version Issues

Permission Errors

PostgreSQL Connection Issues

Environment Variable Issues

Getting Help

Contributing

Next Steps

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Set Up Environment Variables

​Backend Environment

​Frontend Environment

​Generate Encryption Secret

​Step 4: Start PostgreSQL Database

​Verify PostgreSQL is Running

​Step 5: Running the Development Servers

​Option 1: Separate Terminals (Recommended)

​Option 2: Background Processes

​Development URLs

​Step 6: Verify Installation

​Development Workflow

​Hot Reloading

​Available Scripts

​Project Structure

​Troubleshooting

​Common Issues

​Port Already in Use

​Node Version Issues

​Permission Errors

​PostgreSQL Connection Issues

​Environment Variable Issues

​Getting Help

​Contributing

​Next Steps

Prerequisites

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Set Up Environment Variables

Backend Environment

Frontend Environment

Generate Encryption Secret

Step 4: Start PostgreSQL Database

Verify PostgreSQL is Running

Step 5: Running the Development Servers

Option 1: Separate Terminals (Recommended)

Option 2: Background Processes

Development URLs

Step 6: Verify Installation

Development Workflow

Hot Reloading

Available Scripts

Project Structure

Troubleshooting

Common Issues

Port Already in Use

Node Version Issues

Permission Errors

PostgreSQL Connection Issues

Environment Variable Issues

Getting Help

Contributing

Next Steps