Skip to main content

​
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 databases (optional but recommended)

# 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

​
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

# 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'))"

​
Step 4: Set Up Database (Optional)

DeployStack uses SQLite by default for development, but you can optionally set up PostgreSQL: 
No additional setup required. DeployStack will create a SQLite database automatically in services/backend/persistent_data/.

The database file will be created on first run:
services/backend/persistent_data/database/deploystack.db

​
Step 5: Running the Development Servers

DeployStack requires both frontend and backend services to run simultaneously. 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"

​
Development URLs

Once both services are running:

​
Step 6: Verify Installation

1

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
2

Access the Application

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

Create First User

Follow the on-screen setup wizard to create your first admin user and configure basic 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: 
# 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

# 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/ # SQLite database and uploads
│   │   ├── 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

# 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) .

​
Database Connection Issues

# Check if database directory exists
ls -la services/backend/persistent_data/

# Create directory if missing
mkdir -p services/backend/persistent_data/database

# Check database file permissions
ls -la services/backend/persistent_data/database/

​
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

​
Getting Help

If you encounter issues not covered here:
  1. Check Logs: Look at the console output from both frontend and backend servers
  2. Search Issues: Look for similar problems in GitHub Issues
  3. Community Support: Ask for help in our Discord
  4. Create Issue: Report bugs with detailed logs and system information

​
Contributing

Once you have DeployStack running locally:
  1. Read Contributing Guidelines: Check CONTRIBUTING.md
  2. Create Feature Branch: git checkout -b feature/amazing-feature
  3. Make Changes: Implement your feature or bug fix
  4. Test Changes: Run tests and verify functionality
  5. 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!
⌘I