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.
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
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 [email protected]: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
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
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: 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
- 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"
Development URLs
Once both services are running:
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
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) .
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! 
