Metadata-Version: 2.4
Name: domjudge-cli
Version: 0.2.18
Summary: CLI tool for managing DOMjudge contests and infrastructure
Project-URL: Homepage, https://github.com/AnasImloul/domjudge-cli
Project-URL: Repository, https://github.com/AnasImloul/domjudge-cli
Project-URL: Issues, https://github.com/AnasImloul/domjudge-cli/issues
Author-email: Anas IMLOUL <anas.imloul27@gmail.com>
License: MIT
Keywords: cli,contest,domjudge,programming
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: bandit[toml]<2.0,>=1.7.0
Requires-Dist: bcrypt<5.0,>=4.3.0
Requires-Dist: black<25.0,>=24.0.0
Requires-Dist: build>=1.0.0
Requires-Dist: cryptography<44.0,>=43.0.0
Requires-Dist: import-linter<3.0,>=2.0
Requires-Dist: jinja2<4.0,>=3.1.6
Requires-Dist: jmespath<2.0,>=1.0.1
Requires-Dist: mypy<2.0,>=1.11.0
Requires-Dist: p2d<1.0,>=0.3.0
Requires-Dist: pre-commit<4.0,>=3.8.0
Requires-Dist: pydantic<3.0,>=2.11.3
Requires-Dist: pydantic[email]<3.0,>=2.11.3
Requires-Dist: pytest-cov<6.0,>=5.0.0
Requires-Dist: pytest-mock<4.0,>=3.14.0
Requires-Dist: pytest<9.0,>=8.0.0
Requires-Dist: pyyaml<7.0,>=6.0.2
Requires-Dist: requests<3.0,>=2.32.3
Requires-Dist: rich<14.0,>=13.7.0
Requires-Dist: ruff<1.0,>=0.6.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: tqdm<5.0,>=4.67.1
Requires-Dist: typeguard<5.0,>=4.4.2
Requires-Dist: typer<0.18,>=0.15.2
Requires-Dist: types-pyyaml<7.0,>=6.0.12
Requires-Dist: types-requests<3.0,>=2.32.0
Requires-Dist: webcolors<25.0,>=24.11.1
Description-Content-Type: text/markdown

# domjudge-cli

`domjudge-cli` is a command-line tool to set up and manage coding contests on **DOMjudge**.  
It enables you to **declaratively define infrastructure, contests, problems, and teams** using simple configuration files.

Built for **live operations**, it safely applies updates to the platform without requiring downtime.

---

## Key Features

- **Declarative Infrastructure and Contest Management:** Manage everything with YAML files.
- **Infrastructure as Code:** Deploy DOMjudge servers and judgehosts with a single command.
- **Incremental Changes:** Update infrastructure or contests without downtime.
- **Flexible Input Formats:** YAML for configuration; CSV/TSV for teams.
- **Safe Live Modifications:** Apply contest changes while DOMjudge is running.
- **Automatic Config Discovery:** If `--file` is not specified, it will automatically use `dom-judge.yaml` or `dom-judge.yml` (whichever exists first in the current directory).

---

## Installation

```
pip install domjudge-cli
```

Before using `domjudge-cli` to deploy infrastructure, ensure that **cgroups** are enabled on your OS (currently supporting **Ubuntu 22.04**).

1. Create or edit the GRUB configuration:
   
   ```
   sudo vi /etc/default/grub.d/99-domjudge-cgroups.cfg
   ```

   Insert the following line:
   
   ```
   GRUB_CMDLINE_LINUX_DEFAULT="cgroup_enable=memory swapaccount=1 systemd.unified_cgroup_hierarchy=0"
   ```

2. Update GRUB and reboot:

   ```
   sudo update-grub
   sudo reboot
   ```

Only after completing these steps should you attempt to run `domjudge-cli` infrastructure commands.

---

## CLI Usage

Run `dom --help` to see available commands:

```
dom --help
```

Main command groups:

| Command Group | Purpose |
|:--------------|:--------|
| `dom init` | Initialize a new configuration file |
| `dom infra` | Manage infrastructure and platform setup |
| `dom contest` | Manage contests and related configuration |


> **Note for Polygon Users**
> When importing problems from Polygon, ensure the **Package type** is set to **Linux** (not Windows or Standard) for compatibility with DOMjudge.


---

### 1. Initialize a new configuration file

Initialize a new configuration file.

```
dom init
```

if there is a file named `dom-judge.yaml` or `dom-judge.yml` in the current directory, use `--overwrite` to overwrite it.

### 2. Manage Infrastructure

Apply or destroy infrastructure resources.

- **Apply Infrastructure:**

```
dom infra apply --file dom-judge.yaml
```

- **Destroy Infrastructure:**

```
dom infra destroy --confirm
```

If no `--file` is provided, defaults to `dom-judge.yaml` or `dom-judge.yml`.

---

### 3. Manage Contests

Apply contest settings to a running platform.

- **Apply Contest Configuration:**

```
dom contest apply --file dom-judge.yaml
```

If no `--file` is provided, defaults to `dom-judge.yaml` or `dom-judge.yml`.

---

## Configuration Files

Everything is controlled via configuration files in YAML format.

Example: `dom-judge.yaml`

```
infra:
  port: 8080
  judges: 2
  password: "your_admin_password_here"

contests:
  - name: "Sample Contest"
    shortname: "SAMPLE2025"
    start_time: "2025-06-01T10:00:00+00:00"
    duration: "5:00:00.000"
    penalty_time: 20
    allow_submit: true

    problems:
      from: "problems.yaml"

    teams:
      from: "teams.csv"
      delimiter: ','
      rows: "2-50"
      name: "$2"
      affiliation: "$3"
```

Supporting file example: `problems.yaml`

```
- archive: problems/example-problem-1.zip
  platform: "Polygon"
  color: blue

- archive: problems/example-problem-2.zip
  platform: "Polygon"
  color: green

- archive: problems/example-problem-3.zip
  platform: "Polygon"
  color: yellow
```

---

### Team Management

Teams can be defined in a CSV file with the following format:

```csv
id,name,affiliation
1,Team Alpha,INSEA
2,Team Beta,INPT
3,Team Gamma,ENSIAS
```

### Problem Declarations

- Problems for a contest can be **defined directly inside** the contest `problems:` section like this:

```
problems:
  - archive: problems/sample-problem.zip
    platform: "Polygon"
    color: blue
```

- Or you can **abstract the problem list** into a **separate YAML file** and reference it like this:

```
problems:
  from: "problems.yaml"
```

Choose whichever structure better suits your project organization.

---

## Typical Workflow

```
# Initialize a new configuration file
dom init

# Apply infrastructure
dom infra apply --file dom-judge.yaml

# Apply contests, problems, and teams
dom contest apply --file dom-judge.yaml

# (Optional) Destroy infrastructure when done
dom infra destroy --confirm
```

---

## Contest Commands

- `dom contest verify-problemset CONTEST_NAME`: Verify the problemset of the specified contest by running sample submissions to ensure correctness, completeness, and performance limits are met, then report per-problem summaries including mismatches and warnings.

---

## Notes

- Requires Docker installed for infrastructure operations.
- Ensure **cgroups** are properly configured and the system has been rebooted as per Installation instructions.
- DOMjudge API credentials are automatically handled or can be configured.
- Problems and teams must be correctly referenced in the config YAML.
- If no configuration file is explicitly passed with `--file`, the CLI will look for `dom-judge.yaml` or `dom-judge.yml`.

---

# 🎯 Summary

| Action              | Command                                     |
|:--------------------|:--------------------------------------------|
| Initialize a new configuration file | ```dom init``` |
| Deploy platform     | ```dom infra apply --file dom-judge.yaml``` |
| Configure contests  | ```dom contest apply --file dom-judge.yaml```|
| Verify problemset   | ```dom contest verify-problemset CONTEST_NAME``` |
| Destroy everything  | ```dom infra destroy --confirm```           |

---
