Deploying Puter

Introduction

Puter is an open-source, privacy-first internet operating system that runs entirely in your web browser. It provides a full desktop environment with file management, built-in applications, and cloud storage capabilities. Think of it as a complete computer accessible from any device with a web browser.

Puter offers a familiar desktop experience with windows, icons, and menus while being accessible from anywhere. It includes built-in applications for productivity, development, and entertainment, with the ability to add more through its app ecosystem.

Key highlights of Puter:

• Full Desktop Environment: Windows, taskbar, desktop icons, and file manager
• Cloud Storage: Store files in the cloud accessible from anywhere
• Built-in Apps: Text editor, code editor, terminal, and more
• App Development: Create and publish apps using Puter’s SDK
• User Accounts: Multi-user support with individual storage
• API Access: Programmatic access to files and services
• Privacy First: Self-hosted with no third-party tracking
• Cross-Platform: Access from any device with a browser
• Real-Time Sync: Changes sync across all sessions
• Open Source: Licensed under AGPL-3.0

This guide walks through deploying Puter on Klutch.sh using Docker.

Why Deploy Puter on Klutch.sh

Deploying Puter on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Puter without complex configuration.

Persistent Storage: Attach persistent volumes for user files and application data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access.

GitHub Integration: Connect your repository directly from GitHub for automatic deployments.

Scalable Resources: Allocate CPU and memory based on user count and usage.

Custom Domains: Assign a custom domain for your cloud desktop.

Prerequisites

Before deploying Puter on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Puter configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your Puter instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Puter deployment.

Repository Structure

puter-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/nickhysontech/puter:latest

# Set environment variables
ENV PUTER_DOMAIN=${DOMAIN}
ENV PUTER_HTTP_PORT=4100

# Create data directory
RUN mkdir -p /var/puter

EXPOSE 4100

CMD ["node", "src/index.js"]

Alternative Dockerfile from Source

For building from source:

FROM node:20-alpine

WORKDIR /app

# Install git
RUN apk add --no-cache git

# Clone Puter
RUN git clone https://github.com/HeyPuter/puter.git .

# Install dependencies
RUN npm install

# Create data directory
RUN mkdir -p /var/puter

# Set environment variables
ENV NODE_ENV=production
ENV PUTER_HTTP_PORT=4100

EXPOSE 4100

CMD ["npm", "start"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
node_modules

Deploying Puter on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Puter deployment configuration"
git remote add origin https://github.com/yourusername/puter-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “puter” or “cloud-desktop”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Puter Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 4100

Set Environment Variables

Add the following environment variables:

Variable	Value
PUTER_DOMAIN	your-app-name.klutch.sh
NODE_ENV	production

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/puter	100+ GB	User files and data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Puter container
• Provision an HTTPS certificate

Access Puter

Once deployment completes, access your Puter instance at https://your-app-name.klutch.sh. Create an account to start using your cloud desktop.

Using Puter

Desktop Interface

The Puter desktop includes:

• Taskbar: Launch applications and view running apps
• Desktop: Store shortcuts and files
• File Manager: Browse and manage your files
• Start Menu: Access all available applications

Built-in Applications

Application	Description
Files	File manager with drag-and-drop
Editor	Code and text editor
Terminal	Command-line interface
Settings	System configuration
About	System information

File Management

Organize your files:

1. Open the Files application
2. Create folders for organization
3. Upload files via drag-and-drop
4. Share files with shareable links
5. Access files from any device

Keyboard Shortcuts

Shortcut	Action
Alt+F4	Close window
Alt+Tab	Switch windows
Ctrl+C/V	Copy/Paste
F2	Rename file
Delete	Delete selected

Developing Apps for Puter

Puter SDK

Create apps using the Puter JavaScript SDK:

<!DOCTYPE html>
<html>
<head>
    <script src="https://js.puter.com/v2/"></script>
</head>
<body>
    <script>
        puter.ui.alert("Hello from Puter!");
    </script>
</body>
</html>

SDK Features

• File system access
• Key-value storage
• User authentication
• AI capabilities
• UI components

Publishing Apps

1. Create your app using the SDK
2. Host the app files
3. Register in Puter app store
4. Users can install and use your app

API Access

Authentication

Get an API token from Settings > Developer.

File Operations

// Read a file
const content = await puter.fs.read('/path/to/file.txt');

// Write a file
await puter.fs.write('/path/to/file.txt', 'Hello, World!');

// List directory
const files = await puter.fs.readdir('/path/to/directory');

Key-Value Storage

// Store data
await puter.kv.set('myKey', 'myValue');

// Retrieve data
const value = await puter.kv.get('myKey');

User Management

Creating Users

Users can self-register or be created by admins:

1. Go to Settings > Users
2. Create new user accounts
3. Set storage quotas
4. Manage permissions

Storage Quotas

Set storage limits per user:

• Configure default quota
• Adjust individual user limits
• Monitor usage

Troubleshooting Common Issues

Desktop Not Loading

Solutions:

• Clear browser cache
• Try a different browser
• Check JavaScript is enabled
• Review server logs

Files Not Uploading

Solutions:

• Check file size limits
• Verify storage quota
• Check network connection
• Review browser console

Slow Performance

Solutions:

• Increase allocated resources
• Close unused applications
• Clear temporary files
• Optimize file storage

Additional Resources

• Puter Official Website
• Puter GitHub Repository
• Puter Documentation
• Puter Discord Community
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Puter on Klutch.sh gives you a complete cloud desktop environment accessible from any browser. With file management, built-in applications, and extensibility through its SDK, Puter provides a unique approach to personal cloud computing.

Whether you need a portable workspace, a development environment, or a way to access your files from anywhere, Puter on Klutch.sh delivers a full computing experience in your browser.