TSYSDevStack-SupportStack-Cloudron/Package-Workspace/Development/puter/README.md

# Puter Cloudron Package

## Description

Puter is "The Internet OS" - an advanced, open-source internet operating system designed to be feature-rich, exceptionally fast, and highly extensible. Use it as a privacy-first personal cloud to keep all your files, apps, and games in one secure place accessible from anywhere.

## Features

### Core Capabilities
- **Personal Cloud Storage**: Keep all files, apps, and games in one secure place
- **Web App Builder**: Platform for building and publishing websites and web apps
- **Remote Desktop Environment**: Access your desktop environment from anywhere
- **Privacy-First**: Open-source, self-hostable alternative to Dropbox, Google Drive, OneDrive
- **App Store**: Discover and install apps from a growing ecosystem
- **File Manager**: Intuitive file management with drag-and-drop
- **Code Editor**: Built-in code editor for development
- **Terminal**: Web-based terminal for system commands
- **App Development**: Build and publish your own web apps and games
- **Games Platform**: Play browser-based games directly in Puter

### Puter Features
- **Internet OS**: Full operating system experience in the browser
- **File System**: Hierarchical file system with folders and files
- **User Accounts**: Multi-user support with permissions
- **App Integration**: Run multiple apps simultaneously
- **Desktop Interface**: Familiar desktop-like UI
- **Taskbar**: Access running apps and system tools
- **Start Menu**: Quick access to apps and settings
- **Settings Panel**: Configure user preferences and system settings
- **Search**: Fast search across files, apps, and settings
- **Themes**: Customizable appearance with themes
- **Keyboard Shortcuts**: Efficient navigation with shortcuts
- **Drag-and-Drop**: Intuitive file and app management
- **Right-Click Menus**: Context-sensitive menus
- **Window Management**: Multiple windows with minimize/maximize/close
- **Auto-Save**: Automatic save for documents and files
- **Offline Mode**: Basic functionality without internet
- **Mobile Support**: Optimized for mobile browsers

## Configuration

### Environment Variables

#### Application Configuration
- `NO_VAR_RUNCUME`: Assume no variable issues (default: 1)
- Database configuration is auto-managed by Puter

### Ports
- **4100**: Main HTTP port (web interface and API)

### Addons
- **PostgreSQL**: Required for database storage
- **Localstorage**: Used for file storage, app data, and user files

## Usage

### 1. First Time Setup

1. Open Puter
2. Create admin account:
   - Username
   - Email
   - Password
3. Configure system settings:
   - Timezone
   - Language
   - Theme
4. Explore the desktop interface

### 2. File Management

**Upload Files:**
1. Open File Manager app
2. Click "Upload" button
3. Select files from your device
4. Files are uploaded to your personal cloud

**Create Folders:**
1. Navigate to desired location
2. Right-click → "New Folder"
3. Enter folder name
4. Organize files in folders

**Manage Files:**
- Copy/Cut/Paste files
- Rename files
- Delete files
- Move files between folders
- Share files with other users

### 3. Install Apps

**From App Store:**
1. Open App Store
2. Browse available apps
3. Click "Install" on desired app
4. App appears in Start menu

**Install Custom App:**
1. Prepare app code (HTML/CSS/JS)
2. Create folder in File Manager
3. Upload app files
4. Open app by clicking on index.html
5. Pin app to desktop for quick access

### 4. Code Editor

**Create New File:**
1. Open Code Editor app
2. Click "New File"
3. Select language type
4. Start coding

**Edit Existing File:**
1. Navigate to file in File Manager
2. Right-click → "Open with Code Editor"
3. Edit file with syntax highlighting
4. Auto-save keeps changes safe

**Code Features:**
- Syntax highlighting for 100+ languages
- Line numbers
- Code folding
- Find and replace
- Multiple tabs
- Auto-indentation
- Keyboard shortcuts

### 5. Terminal

**Open Terminal:**
1. Click terminal icon in taskbar
2. Enter commands
3. Access system tools and utilities

**Terminal Features:**
- Bash shell
- Command history
- Tab completion
- Copy/paste
- Multiple terminals

### 6. Build Web Apps

**Simple HTML App:**
```html
<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            padding: 20px;
        }
    </style>
</head>
<body>
    <h1>Hello World!</h1>
    <p>This is my first app on Puter.</p>
</body>
</html>
```

**Interactive App with JavaScript:**
```javascript
// Handle user input
document.getElementById('myButton').addEventListener('click', function() {
    const input = document.getElementById('myInput').value;
    alert('You entered: ' + input);
});

// Display current time
function updateTime() {
    const now = new Date();
    document.getElementById('time').textContent = now.toLocaleTimeString();
}
setInterval(updateTime, 1000);
```

**Save and Run:**
1. Save files to File Manager
2. Open index.html
3. App runs in Puter
4. Add to desktop for quick access

### 7. User Management

**Create User:**
1. Open Settings → Users
2. Click "Add User"
3. Configure:
   - Username
   - Email
   - Password
   - Role (Admin, User)
4. Click "Create"

**Manage Permissions:**
- Control file access
- Control app access
- Configure sharing permissions

### 8. System Settings

**General Settings:**
- Timezone
- Language
- Theme (Light/Dark)
- Desktop background
- Font size

**Storage Settings:**
- Check storage usage
- Clean up temporary files
- Manage storage quotas

**Security Settings:**
- Change password
- Configure two-factor authentication
- Review login history

### 9. Keyboard Shortcuts

**Global Shortcuts:**
- `Ctrl + E`: Open File Manager
- `Ctrl + T`: Open Terminal
- `Ctrl + C`: Open Code Editor
- `Alt + Tab`: Switch between apps
- `Win + D`: Show desktop
- `Ctrl + Alt + Delete`: Task Manager

**File Manager:**
- `Ctrl + N`: New file
- `Ctrl + Shift + N`: New folder
- `Delete`: Delete selected file
- `F2`: Rename selected file
- `Ctrl + C`: Copy
- `Ctrl + V`: Paste
- `Ctrl + X`: Cut

**Code Editor:**
- `Ctrl + S`: Save
- `Ctrl + Z`: Undo
- `Ctrl + Y`: Redo
- `Ctrl + F`: Find
- `Ctrl + H`: Replace
- `Ctrl + G`: Go to line

## Architecture

```
                    ┌─────────────┐
                    │   Browser   │
                    └──────┬──────┘
                           │
                    HTTP Request
                           ▼
                   ┌──────────────┐
                   │   Puter     │
                   │  (Node.js)   │
                   │  GUI + API   │
                   └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │ PostgreSQL│  │  Files   │  │  Apps    │
       │ (Database)│  │  Storage  │  │  Store   │
       └──────────┘  └──────────┘  └──────────┘

                   ┌──────────────┐
                   │  Terminal   │
                   │  Code Ed.   │
                   │  File Mgr.  │
                   └──────────────┘
```

## Security

### User Permissions
- Role-based access control (Admin, User)
- File-level permissions
- App-level permissions
- Sharing controls

### Data Protection
- All data stored locally
- No data sent to external services
- Open-source code for audit

### Authentication
- Secure password hashing
- Session management
- Two-factor authentication support

## Troubleshooting

### Apps Not Loading
1. Clear browser cache
2. Check Puter logs: `docker logs <container>`
3. Verify PostgreSQL is running
4. Restart Puter container

### Files Not Uploading
1. Check storage quota
2. Verify file permissions
3. Check network connection
4. Review browser console for errors

### Performance Issues
1. Increase memory limit in Cloudron settings
2. Clean up temporary files
3. Check database performance
4. Reduce number of running apps

## Documentation

For more information on using Puter:
- [Official Website](https://puter.com)
- [Live Demo](https://puter.com)
- [GitHub Repository](https://github.com/HeyPuter/puter)
- [Documentation](https://docs.puter.com)
- [Developer Portal](https://developer.puter.com)
- [Discord Community](https://discord.com/invite/PQcx7Teh8u)
- [Reddit Community](https://reddit.com/r/puter)

## Support

For issues and questions:
- [GitHub Issues](https://github.com/HeyPuter/puter/issues)
- [Discord Server](https://discord.com/invite/PQcx7Teh8u)
- [Reddit](https://reddit.com/r/puter)
- [Twitter/X](https://twitter.com/HeyPuter)

## Upstream

[GitHub Repository](https://github.com/HeyPuter/puter)
[Official Website](https://puter.com)