Codakey
Play
← Back to puter

How to Deploy & Use puter

Puter Deployment and Usage Guide

1. Prerequisites

System Requirements

  • Operating System: Linux, macOS, or Windows
  • RAM: Minimum 2GB (4GB recommended)
  • Disk Space: At least 1GB free space
  • Node.js: Version 24 or higher
  • npm: Latest stable version
  • Git: For cloning the repository

Optional Dependencies

  • Docker: For containerized deployment (optional)
  • Docker Compose: For multi-container orchestration (optional)
  • Redis: Used internally for caching (included in default setup)

2. Installation

Method 1: Local Development (Recommended for Development)

# Clone the repository
git clone https://github.com/HeyPuter/puter
cd puter

# Install dependencies
npm install

# Start the development server
npm start

The application should launch at http://puter.localhost:4100 (or the next available port if 4100 is occupied).

Method 2: Docker Deployment

# Create necessary directories with proper permissions
mkdir puter && cd puter
mkdir -p puter/config puter/data
sudo chown -R 1000:1000 puter

# Run the Docker container
docker run --rm -p 4100:4100 \
  -v `pwd`/puter/config:/etc/puter \
  -v `pwd`/puter/data:/var/puter \
  ghcr.io/heyputer/puter

Method 3: Docker Compose

Linux/macOS:

mkdir -p puter/config puter/data
sudo chown -R 1000:1000 puter
wget https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml
docker compose up

Windows PowerShell:

mkdir -p puter
cd puter
New-Item -Path "puter\config" -ItemType Directory -Force
New-Item -Path "puter\data" -ItemType Directory -Force
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml" -OutFile "docker-compose.yml"
docker compose up

3. Configuration

Environment Variables

Create a .env file in the project root or set these environment variables:

# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_NAME=puter
DB_USER=puter
DB_PASSWORD=your_password

# Redis Configuration (for caching)
REDIS_HOST=localhost
REDIS_PORT=6379

# Session Secret
SESSION_SECRET=your_session_secret_key_here

# API Configuration
API_BASE_URL=http://localhost:4100
NODE_ENV=development  # or 'production'

# Storage Configuration
STORAGE_PATH=/var/puter/data  # For Docker deployments
LOCAL_STORAGE_PATH=./data      # For local development

Configuration Files

The application looks for configuration in:

  • /etc/puter/config.json (Docker volume mount)
  • ./config/config.json (Local development)
  • Environment variables (take precedence)

Example config.json:

{
  "database": {
    "host": "localhost",
    "port": 3306,
    "name": "puter",
    "user": "puter"
  },
  "redis": {
    "host": "localhost",
    "port": 6379
  },
  "security": {
    "session_secret": "your_secret_key"
  },
  "features": {
    "ai_enabled": true,
    "file_sharing": true,
    "app_store": true
  }
}

Required Services

  1. Database: MySQL/MariaDB (configured via DB_* environment variables)
  2. Redis: For caching and session storage (configured via REDIS_* environment variables)
  3. Storage: Local filesystem or cloud storage (configured via STORAGE_PATH)

4. Build & Run

Development Mode

# Install dependencies (if not already done)
npm install

# Start development server with hot reload
npm start

# Or run directly with Node
node src/backend/src/server.js

The development server will be available at http://puter.localhost:4100.

Production Build

# Build the frontend assets
npm run build

# Set environment to production
export NODE_ENV=production

# Start the production server
npm start

Running with Process Manager (PM2)

# Install PM2 globally
npm install -g pm2

# Start Puter in production mode
pm2 start npm --name "puter" -- start

# Save PM2 configuration
pm2 save
pm2 startup

5. Deployment

Platform Recommendations

Self-Hosted Options:

  1. Traditional VPS (DigitalOcean, Linode, Vultr)

    • Minimum: 2GB RAM, 1 CPU, 20GB SSD
    • Install Node.js 24+, MySQL, Redis
    • Use PM2 or systemd for process management

  2. Docker Host (Any platform with Docker)

    • Use provided Dockerfile
    • Map volumes for persistent data
    • Use Docker Compose for multi-service setup

  3. Kubernetes

    • Create deployments for backend, frontend, and services
    • Use ConfigMaps for configuration
    • Persistent volumes for storage

Cloud Platform Options:

  • AWS: EC2 with RDS for database, ElastiCache for Redis
  • Google Cloud: Compute Engine with Cloud SQL and Memorystore
  • Azure: Virtual Machines with Azure Database for MySQL and Azure Cache for Redis

Deployment Steps

  1. Prepare Server:

    # Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 24+
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

# Install MySQL and Redis
sudo apt install -y mysql-server redis-server

  2. Clone and Setup:

    git clone https://github.com/HeyPuter/puter
cd puter
npm install --production

  3. Configure Database:

    sudo mysql -e "CREATE DATABASE puter;"
sudo mysql -e "CREATE USER 'puter'@'localhost' IDENTIFIED BY 'your_password';"
sudo mysql -e "GRANT ALL PRIVILEGES ON puter.* TO 'puter'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

  4. Set Up Environment:

    cp .env.example .env
# Edit .env with your configuration
nano .env

  5. Start Application:

    # Build for production
npm run build

# Start with PM2
pm2 start npm --name "puter" -- start

  6. Set Up Reverse Proxy (Nginx example):

    server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:4100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

6. Troubleshooting

Common Issues and Solutions

1. Port Already in Use

Error: listen EADDRINUSE: address already in use :::4100

Solution: Use a different port or kill the process using port 4100:

# Find and kill process using port 4100
sudo lsof -ti:4100 | xargs kill -9
# Or specify a different port
PORT=4101 npm start

2. Database Connection Errors

Error: connect ECONNREFUSED 127.0.0.1:3306

Solution: Ensure MySQL is running and credentials are correct:

# Check MySQL status
sudo systemctl status mysql
# Start MySQL if stopped
sudo systemctl start mysql
# Verify connection
mysql -u puter -p -e "SELECT 1;"

3. Redis Connection Issues

Error: Redis connection to localhost:6379 failed

Solution: Start Redis server and verify connection:

# Start Redis
sudo systemctl start redis-server
# Test Redis connection
redis-cli ping

4. Permission Denied Errors

Error: EACCES: permission denied, mkdir '/var/puter/data'

Solution: Set proper permissions:

sudo chown -R $USER:$USER /var/puter
# Or for Docker
sudo chown -R 1000:1000 /var/puter

5. Node.js Version Issues

Error: Node.js version must be >= 24

Solution: Update Node.js:

# Using Node Version Manager (nvm)
nvm install 24
nvm use 24
# Or using package manager
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

6. npm Install Fails

Solution: Clear npm cache and retry:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

7. Docker Container Fails to Start

Solution: Check Docker logs and permissions:

# View container logs
docker logs <container_id>
# Check Docker daemon
sudo systemctl status docker
# Ensure proper volume permissions
sudo chown -R 1000:1000 ./puter/data

8. Application Not Accessible

Solution: Verify network configuration:

# Check if server is listening
netstat -tulpn | grep :4100
# Test local access
curl http://localhost:4100
# Check firewall rules
sudo ufw status

Getting Help

Logs Location

  • Local development: Check terminal output and logs/ directory
  • Docker: docker logs <container_name>
  • PM2: pm2 logs puter
  • Systemd: sudo journalctl -u puter.service
← Project overviewView alternatives to puter →