roqueribeiro1988/roqueos-server repository overview

⁠RoqueOS Server

🚀 Unified Backend Server for RoqueOS
Transform your RoqueOS web desktop into a powerful cloud computing platform

⁠ ⁠

⁠🌟 What is RoqueOS Server?

RoqueOS Server is the backend component that unlocks the full potential of RoqueOS⁠ - a web-based operating system interface. While RoqueOS works standalone as a beautiful web desktop, connecting it to RoqueOS Server transforms it into a complete cloud computing platform with real terminal access, remote browsing, file management, and Docker-based applications.

⁠Why Install RoqueOS Server?

⁠✨ Features Unlocked with Server Mode

⁠🐚 Docker-Isolated Terminal

Each user gets their own isolated Ubuntu container with:

• Full Linux command-line access
• Persistent home directory
• Pre-installed development tools (git, curl, wget, vim, nano)
• Resource limits for security

⁠💻 VS Code (Code-Server)

Full Visual Studio Code experience in the browser:

• Integrated code-server with WebSocket proxy
• Dark theme by default
• Access to terminal container filesystem
• Extensions support via Open VSX
• Automatic startup when opening VS Code app

⁠🌐 Remote Browser

Browse the web through a Playwright-powered headless browser:

• Access websites from your server's network
• Bypass CORS restrictions
• Stream video and audio
• Configurable quality settings (FPS, JPEG quality)

⁠📁 File System Management

Complete file management API:

• Upload and download files
• Create, rename, delete files and folders
• Browse your server's file system
• Persistent storage across sessions

⁠📦 Docker App Store

Install and manage Docker-based applications:

• One-click installation from catalog
• Start, stop, restart containers
• View logs and resource usage
• Custom app repositories from roqueos-containers-list⁠

⁠🔐 Secure API Authentication

Enterprise-grade security:

• API Key + Secret authentication
• Permission-based access control
• Admin panel for key management
• Audit logging

⁠🖥️ Remote Desktop (RDP/VNC)

Remote Desktop streaming via Guacamole:

• Create and manage RDP/VNC connections
• Fixed resolution sessions (RDP-like behavior)
• WebSocket stream on /guacamole

⁠📋 Prerequisites

Before installing RoqueOS Server, you need:

1. Docker installed and running
2. Docker Socket accessible (/var/run/docker.sock)
3. Ubuntu Image (required for terminal functionality):

# Pull the Ubuntu image BEFORE starting the server
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

⁠🚀 Quick Start

⁠Option 1: Docker Run (Linux)

# Step 1: Pull the required Ubuntu image
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

# Step 2: Create a shared Docker network (recommended)
docker network create roqueos-network

# Step 3: Start guacd (required for Remote Desktop)
docker run -d \
  --name roqueos-guacd \
  --restart unless-stopped \
  --network roqueos-network \
  guacamole/guacd:1.5.5

# Step 4: Run the server
docker run -d \
  --name roqueos-server \
  --restart unless-stopped \
  --network roqueos-network \
  --add-host=host.docker.internal:host-gateway \
  -p 27021:27021 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /data/roqueos/users:/data/roqueos/users \
  -v /data/roqueos/shared:/data/roqueos/shared \
  -v roqueos-db:/app/data \
  -e GUACD_HOST="roqueos-guacd" \
  -e GUACD_PORT="4822" \
  -e GUACAMOLE_CRYPT_KEY="your-32-char-secret-key-here123" \
  roqueribeiro1988/roqueos-server:latest

⁠Option 2: Docker Run (Windows PowerShell)

# Step 1: Pull the required Ubuntu image
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

# Step 2: Create a shared Docker network (recommended)
docker network create roqueos-network

# Step 3: Start guacd (required for Remote Desktop)
docker run -d `
  --name roqueos-guacd `
  --restart unless-stopped `
  --network roqueos-network `
  guacamole/guacd:1.5.5

# Step 4: Create directories (if needed)
New-Item -ItemType Directory -Force -Path "C:\data\roqueos\users"
New-Item -ItemType Directory -Force -Path "C:\data\roqueos\shared"

# Step 5: Run the server
docker run -d `
  --name roqueos-server `
  --restart unless-stopped `
  --network roqueos-network `
  --add-host=host.docker.internal:host-gateway `
  -p 27021:27021 `
  -v //var/run/docker.sock:/var/run/docker.sock `
  -v C:/data/roqueos/users:/data/roqueos/users `
  -v C:/data/roqueos/shared:/data/roqueos/shared `
  -v roqueos-db:/app/data `
  -e GUACD_HOST="roqueos-guacd" `
  -e GUACD_PORT="4822" `
  -e GUACAMOLE_CRYPT_KEY="your-32-char-secret-key-here123" `
  roqueribeiro1988/roqueos-server:latest

⁠Option 3: Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
  guacd:
    image: guacamole/guacd:1.5.5
    container_name: roqueos-guacd
    restart: unless-stopped
    ports:
      - "4822:4822"

  roqueos-server:
    image: roqueribeiro1988/roqueos-server:latest
    container_name: roqueos-server
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "27021:27021"
    environment:
      - PORT=27021
      - UBUNTU_IMAGE=roqueribeiro1988/roqueos-server-ubuntu:latest
      - GUACD_HOST=guacd
      - GUACD_PORT=4822
      - GUACAMOLE_CRYPT_KEY=MySuperSecretKeyForParamsToken12
      - CONTAINER_MEMORY_LIMIT=2048m
      - CONTAINER_CPU_LIMIT=2.0
      - STORAGE_BASE_PATH=/data/roqueos/users
      - STORAGE_SHARED_PATH=/data/roqueos/shared
      - DATABASE_PATH=/app/data/roqueos.db
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - roqueos-data:/data/roqueos/users
      - roqueos-shared:/data/roqueos/shared
      - roqueos-db:/app/data
    shm_size: "1gb"
    depends_on:
      - guacd
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:27021/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  roqueos-data:
  roqueos-shared:
  roqueos-db:

Then run:

# Step 1: Pull required images
docker pull roqueribeiro1988/roqueos-server:latest
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

# Step 2: Start the server
docker-compose up -d

⁠Verify Installation

Check if the server is running:

curl http://localhost:27021/health

Expected response:

{"status":"ok","timestamp":"...","version":"2.1.0"}

⁠🔑 Generating API Keys (Required)

To connect RoqueOS frontend to your server, you need to generate API credentials.

⁠Step 1: Access Admin Panel

Open your browser and navigate to:

http://YOUR_SERVER_IP:27021/admin

⁠Step 2: Create Initial Admin Key

On first access, you'll see the setup screen:

1. Click "Criar API Key Admin"
2. Save the returned API Key and API Secret securely

⁠Step 3: Connect RoqueOS Frontend

1. Open RoqueOS⁠ in your browser
2. Go to Settings → Server
3. Click + Add Server
4. Fill in the details:
   • Name: My Server (or any name you prefer)
   • URL: http://YOUR_SERVER_IP:27021
   • API Key: (paste from Step 2)
   • API Secret: (paste from Step 2)
5. Click Add & Connect

⁠Step 4: Verify Connection

Once connected, you'll see:

• ✅ Green status indicator next to your server
• ✅ "Remote Browser Quality" settings appear
• ✅ Terminal app now works with real Linux shell
• ✅ File Manager shows your server files

⁠🛠️ Admin Panel

The Admin Panel (/admin) provides a complete management interface:

⁠API Keys Tab

Manage your API keys with full control:

• Create new keys with custom permissions
• View usage statistics
• Regenerate secrets
• Enable/disable keys
• Delete keys

⁠Logs de Uso Tab

Monitor API usage in real-time:

• Filter by API Key, method, endpoint, status
• View request details
• Track usage patterns

⁠Cloudflare Tab

Native Cloudflare Tunnel integration:

• Connect with your Cloudflare account
• Create and manage tunnels
• Configure custom domains
• Add routes for your containers
• Copy Docker commands for cloudflared

⁠🌐 Cloudflare Tunnel Integration

RoqueOS Server includes native Cloudflare Tunnel management directly from the Admin Panel!

⁠Features

⁠Setup Steps

1. Connect - Enter your Cloudflare credentials (Account ID + API Token)
2. Create/Select Tunnel - Create a new tunnel or select an existing one
3. Configure Domain - Set your custom domain and optionally provide Zone ID
4. Add Routes - Map hostnames to your container services
5. Run Cloudflared - Copy the Docker command and run it on your server

⁠API Token Permissions Required

Your Cloudflare API Token needs these permissions:

• Account → Cloudflare Tunnel → Edit
• Zone → DNS → Edit (optional, for automatic DNS records)

⁠⚙️ Environment Variables

⁠💾 Volumes & Persistence

⁠📂 Shared Directory

The shared directory allows you to share files between all RoqueOS components:

⁠🖼️ Screenshots

⁠App Store / Container Catalog

⁠App Install Modal

⁠Installed Apps List

⁠Container Logs

⁠Container WebUI in Browser

⁠System Resource Monitor

⁠Remote Browser - Google

⁠Terminal with htop

⁠Terminal and File Manager

⁠File Manager - Ubuntu Environment

⁠Launchpad with Installed Apps

⁠📡 API Reference

⁠Public Endpoints (No Authentication Required)

⁠Authenticated Endpoints

All require X-API-Key and X-API-Secret headers.

⁠Apps Management

⁠File System

⁠Terminal, VS Code & Browser

⁠System

⁠Remote Desktop

⁠🔄 Updating to a New Version

⁠Using Docker Run

# Step 1: Stop and remove the current container
docker stop roqueos-server
docker rm roqueos-server

# Step 2: Pull the latest images
docker pull roqueribeiro1988/roqueos-server:latest
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

# Step 3: Start the server again (use your original command)
docker run -d \
  --name roqueos-server \
  --restart unless-stopped \
  -p 27021:27021 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /data/roqueos/users:/data/roqueos/users \
  -v /data/roqueos/shared:/data/roqueos/shared \
  -v roqueos-db:/app/data \
  -e GUACAMOLE_CRYPT_KEY="your-32-char-secret-key-here123" \
  roqueribeiro1988/roqueos-server:latest

⁠Using Docker Compose

docker-compose pull
docker-compose up -d

⁠🔧 Troubleshooting

⁠Server not starting?

# Check container logs
docker logs roqueos-server

# Verify Docker socket permissions
ls -la /var/run/docker.sock

# On Linux, add your user to docker group
sudo usermod -aG docker $USER

⁠Cannot connect from frontend?

1. Check network access: Ensure the server is accessible from your browser
2. Firewall rules: Open port 27021 in your firewall
3. API credentials: Verify API Key and Secret are correct
4. CORS errors: Check browser console for CORS issues

⁠Terminal not working?

# Pull the Ubuntu image manually
docker pull roqueribeiro1988/roqueos-server-ubuntu:latest

# Verify the image is available
docker images | grep roqueos-server-ubuntu

# Test container creation
docker run --rm roqueribeiro1988/roqueos-server-ubuntu:latest echo "Container works!"

⁠Remote browser not working?

# Ensure shm_size is set (required for Playwright)
docker run -d --shm-size=1gb ...

# Check if Playwright browsers are installed
docker exec roqueos-server npx playwright install chromium

⁠📦 Related Images

⁠🔗 Links

• Frontend: https://roqueos.com.br⁠
• App Catalog Repository: github.com/roqueribeiro/roqueos-containers-list⁠
• Swagger API Docs: http://YOUR_SERVER:27021/api

⁠🤝 Contributing

The app catalog is open source! You can contribute new apps to the RoqueOS ecosystem:

• Repository: roqueos-containers-list⁠
• See CONTRIBUTING.md for guidelines

⁠📄 License

MIT License - Copyright (c) 2024 Roque Ribeiro

Made with ❤️ by Roque Ribeiro⁠