> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development Setup

> Set up DeployStack for local development with npm scripts and hot reloading.

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](/self-hosted).

<Info>
  For production deployments, use our [Docker Compose setup](/self-hosted/docker-compose) instead.
</Info>

## Prerequisites

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # 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
  ```

  ```bash Windows (WSL) theme={null}
  # 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
  ```
</CodeGroup>

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

## Step 1: Clone the Repository

<CodeGroup>
  ```bash SSH (Recommended) theme={null}
  # 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
  ```

  ```bash HTTPS theme={null}
  git clone https://github.com/deploystackio/deploystack.git
  cd deploystack
  ```
</CodeGroup>

## Step 2: Install Dependencies

Install all project dependencies using npm workspaces:

```bash theme={null}
# Install dependencies for all services
npm install
```

<Info>
  DeployStack uses npm workspaces to manage dependencies across frontend and backend services. The root `npm install` will install dependencies for all services.
</Info>

## Step 3: Set Up Environment Variables

### Backend Environment

Create the backend environment file:

```bash theme={null}
# Create backend .env file
cp services/backend/.env.example services/backend/.env
```

Edit `services/backend/.env` with your configuration:

```bash theme={null}
# 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:

```bash theme={null}
# Create frontend .env file
cp services/frontend/.env.example services/frontend/.env
```

Edit `services/frontend/.env` with your configuration:

```bash theme={null}
# Backend API URL
VITE_DEPLOYSTACK_BACKEND_URL=http://localhost:3000

# App configuration
VITE_APP_TITLE=DeployStack (Dev)
```

### Generate Encryption Secret

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Using OpenSSL (recommended)
  openssl rand -hex 16

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

  ```powershell Windows theme={null}
  # 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'))"
  ```
</CodeGroup>

## 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:

```bash theme={null}
# 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

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

### Verify PostgreSQL is Running

```bash theme={null}
# 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:

```bash theme={null}
# 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:

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # 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"
  ```

  ```powershell Windows theme={null}
  # Start backend in new window
  Start-Process powershell -ArgumentList "-NoExit", "-Command", "npm run dev:backend"

  # Start frontend in current window
  npm run dev:frontend
  ```
</CodeGroup>

### Development URLs

Once both services are running:

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

## Step 6: Verify Installation

<Steps>
  <Step title="Check Service Status">
    Verify both services are running:

    ```bash theme={null}
    # Check if ports are listening
    curl http://localhost:3000/health  # Backend health check
    curl http://localhost:5173         # Frontend dev server
    ```
  </Step>

  <Step title="Access the Application">
    Open [http://localhost:5173](http://localhost:5173) in your browser. You should see the DeployStack interface.
  </Step>

  <Step title="Complete Setup Wizard">
    Follow the on-screen setup wizard to:

    * Configure PostgreSQL database connection
    * Create your first admin user
    * Set up basic platform settings
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# Check Node version
node --version

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

#### Permission Errors

<CodeGroup>
  ```bash Linux/macOS theme={null}
  # Fix npm permissions
  sudo chown -R $(whoami) ~/.npm

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

  ```text Windows theme={null}
  Run your terminal as Administrator or ensure you have write permissions to the project directory.
  ```
</CodeGroup>

#### PostgreSQL Connection Issues

```bash theme={null}
# 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

```bash theme={null}
# 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:

1. **Check Logs**: Look at the console output from both frontend and backend servers
2. **Search Issues**: Look for similar problems in [GitHub Issues](https://github.com/deploystackio/deploystack/issues)
3. **Community Support**: Ask for help in our [Discord](https://discord.gg/UjFWwByB)
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](https://github.com/deploystackio/deploystack/blob/main/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](http://localhost:3000/documentation)
* **Join Development Discussions**: Participate in our [Discord](https://discord.gg/UjFWwByB) development channels
* **Check Open Issues**: Find issues to work on in our [GitHub repository](https://github.com/deploystackio/deploystack/issues)

***

**Ready to contribute?** Check our [Contributing Guidelines](https://github.com/deploystackio/deploystack/blob/main/CONTRIBUTING.md) to get started!