Skip to content

Beacon documenation #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LuckyIntegral merged 3 commits into from
Mar 10, 2025
Merged

Beacon documenation #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9739725
fix: add proper error handling for missed file
LuckyIntegral Mar 7, 2025
3e033c9
docs: add user friendly readme
LuckyIntegral Mar 7, 2025
94d2c62
docs: update readme
LuckyIntegral Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
320 changes: 72 additions & 248 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,267 +1,91 @@
# Dash - Marvin
# Dash Competition Framework

## Overview

**Dash** is a Go-based framework designed to facilitate the launch and management of programming competitions. It automates repository creation, manages participants, handles submissions, and provides tools for analysis and visualization of results.
Dash is a competition framework designed to run and visualize programming-based challenges. It supports multiple competitions, with current implementations for **Beacon** and **Marvin**.

## Table of Contents

- [Features](#features)
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [.env File](#env-file)
- [participants.json](#participantsjson)
- [maps.json](#mapsjson)
- [Usage](#usage)
- [CLI Menu](#cli-menu)
- [Running the Visualizer](#running-the-visualizer)
- [Project Structure](#project-structure)
- [Go Version & Dependencies](#go-version--dependencies)
- [Taskfile](#taskfile)

## Features
- [Running the Competition](#running-the-competition)
- [Results & Logs](#results--logs)
- [Visualization](#visualization)
- [Scripts](#scripts)
- [License](#license)

- **Automated Repository Management:** Create GitHub repositories from a template.
- **Participant Handling:** Manage teams and their associated competitions.
- **Submission Analysis:** Clone and evaluate participant submissions.
- **Trace Uploading:** Push test traces to specific branches for review.
- **Result Generation:** Compile logs into comprehensive JSON results for visualization.
- **Docker Integration:** Safe execution of user programs in isolated environments.
- **Interactive CLI:** User-friendly menu for managing various tasks.
- **Visualizer:** JavaScript-based tool for displaying competition results.
## Overview
Dash enables participants to compete in programming challenges by providing executable solutions. The framework supports:
- Multiple competitions with modular grading
- Configuration-driven execution
- Automated logging and result storage
- Visualization tools for performance analysis

## Prerequisites

- **Go:** Version 1.22
- **Docker:** For running the visualizer and executing user programs securely.
- **GitHub Access Token:** Must have permissions to create repositories and manage access.
- **Organization:** The GitHub organization where repositories will be created must already exist and contain a `template-marvin` repository.
Ensure you have the following installed before proceeding:
- **Taskfile** - Required for running compilation tasks (*optional*)
- **Docker** - Used for containerized execution
- **Git** - Necessary for managing participant repositories
- **GitHub Organization** – A dedicated organization where all repositories will be created
- **template-{competition}** Repository – A template repository inside *the dedicated organization* used for initializing participant repositories

### API Token
For authentication and repository management, a valid **GitHub Personal Access Token (PAT)** is required. The token must have the following scopes:
- `admin:org`
- `repo`
- `delete_repo`

## Installation

1. **Clone the Repository:**
```bash
git clone https://github.com/your_org/dashinette.git
cd dashinette
```

2. **Install Dependencies:**
```bash
go mod download
```

## Configuration

### `.env` File

Create a `.env` file in the root directory based on the `.env.example`:

```env
ORGANIZATION_NAME=your_github_org
GITHUB_ACCESS_TOKEN=your_access_token
```

- **ORGANIZATION_NAME:** Name of the GitHub organization where repositories will be created.
- **GITHUB_ACCESS_TOKEN:** Token with permissions to create repositories and manage collaborators.

#### `participants.json` configuration file
Defines the teams participating in the competition.

```json
{
"teams": [
{
"name": "The-Avengers",
"members": ["IronMan", "Thor777"],
"league": "open"
},
{
"name": "Pirates-of-the-Caribbean",
"members": ["jack-sparrow", "wturner"],
"league": "open"
},
{
"name": "The-Justice-League",
"members": ["BatmanIsHere", "SuPeRmAn"],
"league": "rookie"
}
]
}
```
- **name:** Team name.
- **members:** List of team members.
- **league:** Competition league (`open` or `rookie`).

#### `maps.json` configuration file
Specifies the maps used for generating traces for tests and final submittions.

```json
{
"rookieleague": [
{
"path": "dashes/marvin/maps/rookieleague/amongus.txt",
"name": "Impostor",
"timeout": 2
},
...
],
"openleague": [
{
"path": "dashes/marvin/maps/openleague/sipmson.txt",
"name": "You know him",
"timeout": 3
},
...
]
}
```

- **path:** File path to the map.
- **name:** Map name.
- **timeout:** Execution timeout in seconds.

## Usage
### CLI Menu
Launch the CLI with:
```bash
go run main.go
```

#### Menu Options:

1. **Create GitHub Repositories by template:** Initializes repositories for each team based on the `template-marvin` repo.
2. **Update README files with Subjects:** Pushes updated subjects to team repositories.
3. **Grant Collaborator Write Access:** Adds collaborators with write permissions to repositories.
4. **Configure Repositories as Read-Only:** Sets repositories to read-only access.
5. **Clone and Analyze Submissions to Generate Traces:** Clones student submissions and generates trace data.
6. **Parse and Upload Traces to 'traces' Branch:** Uploads generated traces to the `traces` branch of each repository.
7. **Parse Logs and Generate results.json:** Compiles logs into a `results.json` file for visualization.
8. **Exit:** Closes the CLI.

### Example Workflow

1. Create Repositories:
- Select "Create GitHub Repositories by template."
2. Add collaborators:
- Select "Grant Collaborator Write Access."
3. Analyze Submissions and give feedback
- Select "Clone and Analyze Submissions to Generate Traces."
- Select "Parse and Upload Traces to 'traces' Branch."
4. Analyze Submissions and prepare results for visualization:
- Select "Clone and Analyze Submissions to Generate Traces."
- Select "Parse Logs and Generate results.json."

All actions are logged in `app.log` for detailed tracking.

### Running the Visualizer
The visualizer is a Dockerized JavaScript application that displays competition results.

1. **Launch the Visualizer:**
```bash
go run scripts/marvin/visualiser/start/main.go generated_results.json
Clone the repository:
```sh
# Clone the repository
git clone https://github.com/42-Dash/dashinette.git
cd dashinette
```

2. **Access the Visualizer:** Open your browser and navigate to `http://localhost:8080`.
```bash
.
├── README.md
├── Dockerfile
├── Taskfile.yml
├── app.log
├── cmd
│ └── marvin
│ ├── tester
│ ├── tests
│ └── marvin
├── config
│ ├── .env
│ ├── maps.json
│ └── participants.json
├── dashes
│ └── marvin
│ ├── README.md
│ ├── maps
│ ├── repos
│ ├── solutions
│ ├── traces
│ └── visualiser
│ ├── Dockerfile
│ ├── images
│ ├── index.html
│ ├── libraries
│ ├── results.json
│ └── src
├── go.mod
├── go.sum
├── internals
│ ├── cli
│ ├── grader
│ └── traces
├── main.go
├── pkg
│ ├── constants
│ ├── containerization
│ ├── github
│ ├── logger
│ └── parser
└── scripts
## Configuration
All configuration files are stored in the `config/` directory:
- **`maps.json`** – Defines competition maps
- **`participants.json`** – Lists participating teams
- **`.env`** – Stores environment variables

### `.env` Example
Create a `.env` file in `config/` with the following format:
```sh
GITHUB_ACCESS=your_github_access_token
GITHUB_ORGANISATION=your_github_organisation
```

## Go Version & Dependencies
- Go Version: 1.22

**Dependencies:**
```go
module dashinette

go 1.22

require (
github.com/docker/docker v27.3.1+incompatible
github.com/joho/godotenv v1.5.1
github.com/manifoldco/promptui v0.9.0
)
## Running the Competition
Dash competitions are compiled and executed using Taskfile:
```sh
# Run the contest using Taskfile
task {competition to start}
# Or run the contest directly
go run cmd/{competition}/{competition}/main.go
```

## Taskfile

The project utilizes a [`Taskfile.yml`](Taskfile.yml) to automate various development tasks. [Task](https://taskfile.dev/) is a simple task runner that helps streamline your workflow.

### Prerequisites

- **Task:** Ensure Task is installed on your system. Follow the [Task installation guide](https://taskfile.dev/installation/) to set it up.

### Available Tasks

- **marvin:** Build the marvin project.
- **marvin-tester:** Build the marvin project tester (for development).
- **marvin-docker:** Rebuild the Docker image for the marvin project.
- **clean:** Clean up the repository by removing build artifacts and logs.
- **delete-repos:** Remove the organization repositories. **Use with caution.**
- **test:** Run all tests and clean up afterwards.

### Usage

To execute a task, use the following command:

```bash
task <task-name>
This launches a CLI menu allowing you to:
- Initialize repositories
- Analyze submissions
- Run grading and visualization
- Manage collaborators

## Results & Logs
Competition results and logs are stored in the root directory:
- `app.log` – Stores execution logs
- `open_results.json` – Results for Open League
- `rookie_results.json` – Results for Rookie League

## Visualization
Each competition has a dedicated visualizer located in:
```sh
dashes/{competition}/visualiser/
```
Detailed documentation for visualizers can be found in the respective `README.md` files.

### Examples:

- **Build the marvin project:**

```bash
task marvin
```

### Viewing Help
To view available commands and their descriptions:

```bash
task help
```
## Scripts
Additional scripts are available in `scripts/general/`:
- **`delete_repos.sh`** – Deletes all competition repositories
- **`reshuffle_config.sh`** – Randomizes participant order for fairness

This will display all available tasks with their respective descriptions.
## License
The project license will be added soon. See `LICENSE` for more details.
Loading
Loading