HandyCafe Docs
owner it-admin

How to Set Up Cafeteria

This guide walks through the complete first-time setup of the Cafeteria module. By the end you will have a published customer menu at handy.cafe/{your-slug}, a floor plan with at least one working table, a menu with products, and a successfully placed test order.

What You Will Need

  • An active HandyCafe license. Cafeteria authentication uses the license automatically; you do not paste a key manually.
  • Internet connectivity on the server. Cafeteria is cloud-first, so provisioning, menu sync, and order polling all require outbound access to the cloud API.
  • A slug you want to use for the public menu URL. Allowed characters are lowercase letters, numbers, and dashes. Length is 3 to 62 characters.
  • Optional: a logo and header image. Recommended format is WebP up to 2 MB.
  • Optional: a TCP receipt printer on the local network.

Step 1: Enable Cafeteria

  1. Open the HandyCafe Server.
  2. Navigate to Settings in the sidebar.
  3. Open the Cafeteria tab.
  4. Toggle Enable Cafeteria to on.
  5. The server contacts the cloud API using your license as the authorization token. If successful, the Provisioning Wizard opens.

Expected result: The Provisioning Wizard screen appears. If you see an error about license or connectivity, check your internet connection and confirm your HandyCafe license is active.

Step 2: Provision Your Cafe

The wizard asks for four fields.

  1. Slug. Type your desired URL suffix. The availability indicator updates within a second. If the slug is taken or reserved, choose a different one.
  2. Display Name. The human-readable name shown at the top of the customer menu, for example "Atilla's Gaming Lounge".
  3. Country and Currency. Pick the country where the cafe operates. The currency defaults based on the country and can be changed.
  4. Timezone. Pick the timezone for order and settlement time stamps.
  5. Click Create Cafe.

Expected result: The wizard closes and the Cafeteria workspace opens. Your public URL handy.cafe/{slug} is now live, though the menu is empty.

Step 3: Fill In the Business Profile

  1. Still under Settings > Cafeteria, scroll to the Business Profile section.
  2. Upload a Logo (square image).
  3. Upload a Header Image (wide banner).
  4. Enter the Address and Phone to display in the footer of the customer menu.
  5. Toggle Show Prep Time on Menu on or off depending on whether you want customers to see estimated preparation times.
  6. Click Save.

Expected result: The logo and header appear in a preview. Visiting handy.cafe/{slug} in a browser now shows the branded header but still empty content.

Step 4: Create Floors

  1. In Settings > Cafeteria, find the Floors section.
  2. Click Add Floor and name it (for example "Main Hall").
  3. Add additional floors if your venue has multiple areas (for example "Mezzanine", "Outdoor Patio").
  4. Reorder floors with the move-up and move-down buttons. The top floor becomes the default in the Floor Plan editor.

Expected result: Your floors appear in the list. The Cafeteria > Floor Plan tab now shows the floor pills at the top.

Step 5: Build the Floor Plan

  1. Open Cafeteria > Floor Plan.
  2. Select the first floor from the pills.
  3. Click Add Table. A square table appears at the canvas origin.
  4. Drag the table to the desired position. Release to save.
  5. Click the table to open its properties panel. Configure:
    • Code (for example "T1", "Window 3").
    • Display Name (optional longer label).
    • Seat Count (number of seats).
    • Shape (square, rectangle horizontal, rectangle vertical, or round).
    • Size (1 to 10).
  6. Repeat for every table in the floor.
  7. Optionally switch to 3D view to review the layout from an architect perspective.

Expected result: Your floor plan renders all tables at their real-world positions. Drag is disabled in 3D view; switch back to 2D to move tables.

Step 6: Build the Menu

  1. Open Cafeteria > Menu.
  2. Click Add Category. Enter a name and pick an MDI icon from the icon picker. Click Save.
  3. Repeat for each category (for example "Hot Drinks", "Cold Drinks", "Burgers", "Desserts").
  4. Inside a category, click Add Product. Enter:
    • Name.
    • Description (Markdown supported).
    • Ingredients line.
    • Base Price.
    • VAT Rate.
    • Preparation Time (static fallback).
    • Optional: Unit label, Track Stock flag, In Stock count.
  5. Upload a product Photo. Any format is accepted; WebP up to 2 MB is recommended.
  6. Click Save.
  7. If the product has choices, scroll to the Variants section and click Add Variant. Create a row for each option with its price delta. Toggle Required if the customer must pick one.
  8. Repeat for every product in your menu.

Expected result: The customer menu at handy.cafe/{slug} now shows your categories and products. Visit it in a browser to verify.

Step 7: Configure the Printer (Optional)

  1. Still under Settings > Cafeteria, scroll to Printer Settings.
  2. Set Kind to TCP.
  3. Enter the printer IP and Port. Most ESC POS TCP printers listen on port 9100.
  4. Enable Auto Cut if the printer supports it.
  5. Enable Auto Print on New Order to trigger a print for every incoming order.
  6. Enable Sound Notification for an audio alert alongside the desktop notification.
  7. Click Test Print. A sample receipt should print within a few seconds.

Expected result: The test receipt prints successfully. If nothing prints, verify the IP, port, and that the printer is on the same local network as the server.

Step 8: Seat a Table and Take a Test Order

  1. Open Cafeteria > Tables (or use the Floor Plan action menu).
  2. Pick one table and click Seat Customer (also labeled "Open Table").
  3. Note the 6-digit security code displayed. Write it down or leave the dialog open.
  4. On a phone, navigate to handy.cafe/{slug}/{table-code}. You can also scan the QR if you have a printed sticker.
  5. Enter the 6-digit code.
  6. Browse the menu and add an item to the cart.
  7. Proceed to checkout. Pick Cash as the payment method (Stripe setup is optional and can be added later).
  8. Submit the order.
  9. On the server, switch to Cafeteria > Orders.

Expected result: Within 3 seconds, a new order card appears on the Orders dashboard. A desktop notification fires. An audio alert plays if sound notifications are enabled. The pending-count badge increments on the Orders tab.

Step 9: Advance and Settle the Test Order

  1. On the order card, click the next status button. The order moves from placed to confirmed.
  2. Continue clicking to progress through preparing, ready, and served.
  3. On the Tables page, open the same table and click Settle Check.
  4. Pick Cash as the payment method and confirm.

Expected result: The table returns to idle. The security code is expired. A settlement record is created and can be audited later.

Common Mistakes to Avoid

  • Skipping the business profile. Customers see the default display name and a broken logo area if you launch before saving the profile.
  • Not reprinting QR codes after slug changes. Changing the slug invalidates every existing QR. Print fresh stickers and replace on every table.
  • Publishing too many categories at launch. Aim for 6 to 10 top-level categories. Customers browse faster when the menu fits the screen.
  • Forgetting to configure the printer before the first real shift. Without Auto Print on New Order, staff may miss orders during a busy period. Always run at least one test print.
  • Leaving the default Show Prep Time on Menu enabled with no dynamic history. For the first 30 days the static value is what customers see. Set realistic static times or disable the chip until the dynamic estimate has trained.
  • Using the same device for staff and customer testing. The customer session persists for 24 hours; if your test device was later handed to a customer, they would already be on the menu without verification. Clear the device or use a clean browser profile for tests.