HandyCafe Docs
it-admin

Getting Started: IT Administrator

This guide covers the technical setup of HandyCafe. By the end, you will have the server and clients installed, network configured, app menus built, and remote management tested.

Time to complete: 5 minutes (plus client deployment time)

Step 1: Install the Server and Clients

Server installation:

  1. Verify your server PC meets the system requirements.
  2. Download and install HandyCafe Server on your management PC.
  3. Launch the server and complete the First Setup Wizard to create the admin account.
  4. Note the server PC's local IP address. Clients will need this to connect.

Client installation (repeat for each PC):

  1. Download HandyCafe Client on each customer-facing PC.
  2. Install and launch the client.
  3. The client searches for the server on the local network using mDNS discovery.
  4. If the server is not found automatically, enter the server IP address manually in the client settings.
  5. Once connected, the client appears on the server's Admin Panel.

Tip: Use the server's auto-naming feature (Settings > Clients) to automatically name clients with a prefix like "PC #1", "PC #2", etc. You can customize display names later.

See Server Installation and Client Installation for detailed steps.

Step 2: Configure Network Settings

Navigate to Settings > Network on the server.

HandyCafe uses four ports for communication:

Port Default Purpose
TCP Port 5001 Command and response communication
File Port 5002 File transfers between server and clients
Remote Management Port 5003 Remote desktop streaming control
UDP Port 5004 Screen streaming data

Configuration:

  1. Set the ports (defaults work for most setups).
  2. Set the Connection Key. This is a shared secret used for HMAC-SHA256 authentication. All clients must use the same key.
  3. Click Save.

Firewall rules:

Ensure these ports are open on both the server and client PCs:

  • TCP: 5001, 5002, 5003 (inbound on server, outbound on clients)
  • UDP: 5004 (bidirectional for screen streaming)

Important: All PCs must be on the same local network (subnet). HandyCafe uses mDNS for client discovery, which requires LAN connectivity.

See Network Settings for all network options.

Step 3: Set Up the Client Menu

The client menu is the app launcher that customers see on their desktop. Navigate to Settings > Clients > Content tab.

  1. Create categories. Group apps by type (e.g., Games, Browsers, Social Media, Tools).
  2. Add apps to each category:
    • Set the app name and description.
    • Choose the app kind: Game, Browser, Link, File, or App.
    • Set the executable path or launch URI.
    • Upload an icon and optionally a poster image for the app card.
  3. Reorder categories and apps using drag handles.
  4. Toggle visibility to show or hide items.
  5. Click Save.

Changes are pushed to all connected clients automatically in real time via TCP.

Tip: Use the IGDB integration to search for game metadata and icons automatically.

See Client Menu for the complete menu builder documentation.

Step 4: Configure Idle Screen and Appearance

Idle Screen (Settings > Clients > Idle Screen tab):

The idle screen is what customers see when no session is active (the lock screen).

  1. Enable the idle screen slideshow.
  2. Add images or videos (PNG, JPG, WebP, GIF, MP4, WebM).
  3. Set the duration per item and transition effect (fade, slide, zoom).
  4. Optionally enable a clock overlay and cafe name display with custom colors.
  5. Click Save.

Appearance (Settings > Clients > Appearance tab):

Configure the look of the online desktop that customers use during sessions.

  1. Select a theme: Neon Arena, Crimson Pulse, or Emerald Depth.
  2. Choose a layout preset: Split Classic, Hero Wide Top, Catalog Wide Bottom, or Compact Focus.
  3. Configure background: solid color, gradient, image, or video with overlay and blur settings.
  4. Adjust card density (Large, Medium, Compact) and hover effects.
  5. Click Save.

See Client Idle Screen and Client Appearance for all options.

Step 5: Test Remote Desktop and Screenshots

Verify that remote management works:

Screenshots:

  1. On the Admin Panel, select any online client card.
  2. Click Screenshot on the client card.
  3. A screenshot of the client's screen appears in the viewer.
  4. You can download or refresh the screenshot.

Remote Desktop:

  1. Select an online client card and click Remote Desktop.
  2. A remote desktop window opens with live H.264 streaming.
  3. You can control the mouse and keyboard on the remote PC.
  4. Clipboard synchronization works between server and client.

Note: Remote desktop uses UDP streaming. If the video is laggy, check your network bandwidth and ensure UDP port 5004 is not blocked. You can also adjust the bitrate in the stream settings (350-25,000 kbps).

See Remote Desktop and Screenshots for all remote features.

Network Architecture Overview

Server PC (Management)
    |
    |--- TCP (5001) --- Command/Response (bincode + HMAC-SHA256)
    |--- TCP (5002) --- File Transfers
    |--- TCP (5003) --- Remote Management Control
    |--- UDP (5004) --- Screen Streaming (H.264)
    |--- mDNS ------- Client Discovery (automatic)
    |
    +-- Client PC 1
    +-- Client PC 2
    +-- Client PC 3
    +-- ...

What to Do Next