Introduction

Pomelo User Guide

What This Guide Covers

This guide walks you through the full lifecycle of using Pomelo, from launching the platform with the CLI, to configuring infrastructure through the Admin UI, to creating and managing assessments in the main App.

Whether you are an administrator setting up Pomelo for the first time or an instructor building your first coding contest, follow along in order. Each section builds on the previous one.

Pomelo CLI

Getting Started with the CLI

The pomelo command is your primary tool for managing a Pomelo deployment from the terminal. It is installed automatically during setup and symlinked to /usr/local/bin/pomelo.

Starting Pomelo

After installation, launch the entire platform (Docker containers, databases, the web server, and the Judge0 code evaluation engine) with a single command:

The CLI streams progress to your terminal as each service comes online. Once complete, your Pomelo instance is ready for use.

Checking Status

To verify that all services are healthy and running:

This prints the state of each Docker container (running, stopped, or errored) along with the daemon version.

Stopping Services

When you are done or need to free system resources:

All containers are gracefully stopped. Your data is preserved on disk.

Restarting Services

If you have made configuration changes (for example, updating environment variables or domain settings), apply them by restarting:

CLI Command Reference

The full set of commands available through the pomelo CLI:

Viewing Logs

You can tail logs for any individual service by name:

This is useful for debugging startup failures, network issues, or unexpected submission errors without opening the Admin UI.

Opening the Admin UI

Instead of remembering the port number, use the built-in shortcut:

This opens http://localhost:8462 (or your configured Admin CLI port) in your default browser.

Admin UI

Dashboard

The Admin UI is Pomelo’s dedicated interface for infrastructure management. Open it with:

System Status

The Dashboard is the first thing you see when you enter the Admin UI. It provides a bird’s-eye view of your deployment across three key metrics:

Quick Actions

Below the status indicators, you will find action buttons that mirror the CLI:

These are identical to running pomelo start, pomelo stop, and pomelo restart in the terminal.

Container List

A live table of all containers is displayed at the bottom of the Dashboard. Each row shows the container name and a status badge:

Storage Overview

At the bottom, you will see a summary of disk usage split into Database, Uploads, and Backups. Use this to monitor growth over time.

Setup & Configuration

The Setup page is where you configure the core infrastructure services that power Pomelo. Navigate to it from the Admin UI sidebar.

MongoDB

Choose how Pomelo connects to its primary database:

If you choose External, you can click Test Connection to verify read/write access before saving. If the test fails, the save is aborted so you do not accidentally break your deployment.

Judge0 Engine

Configure the code evaluation backend:

Domain & Protocol

Set the public-facing address for your Pomelo instance:

Environment Variables

The Environment tab gives you direct access to Pomelo’s raw environment configuration. Instead of manually editing .env files on the server, you can update values through this interface.

What You Can Configure

Workflow

1. Open the Environment tab in the Admin UI sidebar.
2. Locate the variable you want to change.
3. Edit the value inline and click Save.
4. Return to the Dashboard and click Restart to apply the changes.

User Management

The Users page in the Admin UI is for managing accounts that access the Pomelo application. Users are stored in MongoDB and split into two tabs: Administrators and Regular Users.

Creating an Account

1. Click the Add Account button in the top-right corner.

2. Fill in the form fields:

   Field	Description
   Name	Display name for the account (optional, max 100 characters).
   Email	Must be a valid email address (required).
   Password	Minimum 6 characters, maximum 72 (required).
   Role	Select either Admin or User.

3. Click Create Account.

Admin accounts created here can log into the main Pomelo App and access the /admin dashboard, where tests and questions are managed.

Managing Existing Accounts

The user table displays all accounts for the selected role tab. For each account you can:

Pagination

When you have many accounts, the table automatically paginates. Use the Previous and Next buttons to navigate between pages.

Logs & Debugging

The Logs tab provides a real-time, streaming view of your container output. It is the fastest way to diagnose service failures without dropping into a terminal.

When to Use Logs

• A service fails to start after running pomelo start or clicking Start on the Dashboard.
• A candidate’s code submission fails unexpectedly or times out.
• You see container status badges showing “Exited” on the Dashboard and want to know why.

Filtering by Container

You can scope the log stream to a specific container to reduce noise:

CLI Alternative

You can also tail logs from the terminal without opening the Admin UI:

Authentication

The Pomelo App is the main web interface where instructors create assessments and candidates take them. Open it by navigating to your configured domain in a web browser.

Creating an Account

1. On the landing page, click Sign Up.
2. Enter your name, email address, and a password.
3. Click Register to create your candidate account.

You are now logged in and can browse available contests or join a test using a code.

Logging In

If you already have an account:

1. Click Login on the landing page.
2. Enter your email and password.
3. Click Sign In.

Admin Access

To access the App Admin dashboard (where tests and questions are created), you must log in with an account that has the Admin role. Admin accounts are created through the Admin UI → Users page, not through the App’s sign-up form.

Once authenticated as an Admin, you will have access to the /admin route and all management features.

Pomelo App

Dashboard

Once logged in as an Admin, you are taken to the App Admin dashboard at /admin. This is your home base for managing assessments.

Dashboard Overview

The dashboard surfaces key metrics at a glance:

Question Bank Breakdown

Below the main stats, you will see a breakdown of your question bank by difficulty:

Recent Tests

A list of your most recently created tests is displayed at the bottom. Each entry shows the test title, status (waiting, ongoing, or completed), duration, question count, and participant numbers. Click on any test to jump directly to its management page.

Creating a Test

Tests are the core unit of assessment in Pomelo. Each test is a timed container for questions that candidates work through.

Step-by-Step

1. Navigate to the Admin Dashboard in the main app (/admin).
2. Click the Create Test button.
3. Fill in the foundational details:

4. Click Save. You will be redirected to the test management page where you can add questions.

Test Management

Once created, the test management page at /admin/tests/[id] gives you access to:

Adding MCQ Questions

Multiple Choice Questions (MCQs) are ideal for testing theoretical knowledge, definitions, and conceptual understanding.

Step-by-Step

1. Open the test you want to add questions to (from the Admin Dashboard or via /admin/tests/[id]).
2. Navigate to the Questions section.
3. Click Add Question and select Multiple Choice Question (MCQ).
4. Fill in the question details:

5. Click Save Question.

Tips

• Write clear, unambiguous prompts. Avoid trick questions unless intentional.
• Include plausible distractors (options that look correct but are not) to genuinely test understanding.
• Assign point values that reflect the difficulty of the question relative to other questions in the test.
• You can return to any saved question and edit it as long as the test has not started.

Adding Code Questions

Code questions allow candidates to write and submit programs that are automatically compiled, executed, and graded against predefined test cases using the Judge0 engine.

Step-by-Step

1. Open the test’s Questions section.
2. Click Add Question and select Code Question.
3. Fill in the problem details:

Adding Test Cases

Test cases are the backbone of automated grading. For each test case:

1. Click Add Test Case.

2. Provide the Standard Input (the exact input your program will receive via stdin).

3. Provide the Standard Output (the expected output the program must produce).

4. Set the visibility:

   Visibility	Description
   Public	Visible to candidates as a sample/example. They can use this to verify their approach.
   Hidden	Used only for final grading. Candidates never see the input or expected output.

5. Click Save Question when you are done adding all test cases.

Best Practices

• Include at least 1–2 public test cases so candidates can validate their solution before submitting.
• Add edge cases as hidden test cases (empty input, maximum constraints, boundary values) to ensure solutions are robust.
• Write the problem statement as if the candidate has never seen the problem before. Include input/output format specifications and a worked example.

Scheduling & Joining Tests

Once your test is populated with questions, configure its start and end times to schedule it for candidates.

Scheduling a Test

1. Navigate to the test management page (/admin/tests/[id]).
2. Click Edit to configure the Start Time and End Time.
3. Ensure the times are correct. A unique join code is generated automatically when the test is created.

Share this join code (or the direct test link) with your candidates through email, a messaging platform, or a classroom portal. Candidates can use the code to join, but the test will only open when the scheduled start time is reached.

Candidate Journey

From the candidate’s perspective:

1. Navigate to the Pomelo App in their browser.
2. Log in or Sign up for a candidate account.
3. Go to the Join page at /join.
4. Enter the join code provided by the instructor.
5. Begin the attempt: they are redirected to the /attempt interface where the timer starts and questions are presented.

During the Attempt

• The countdown timer is visible at all times.
• Candidates can navigate between questions freely.
• MCQ answers are saved immediately on selection.
• Code submissions are sent to Judge0 for evaluation. Candidates see results for public test cases in real time.
• When time expires, the attempt is automatically submitted.

After the Test

• Admins can view the Leaderboard for live rankings.
• The Submissions tab shows every candidate’s individual answers.
• The Results page provides final scores and analytics.