Administrative Procedures

Maintenance Mode

You can turn on maintenance mode by creating a maintenance.on file in the maintenance_mode folder. This will change the front page of the website, showing a customizable page (the maintenance.html file in the same folder).

Simply remove the maintenance_mode/maintenance.on file to end maintenance mode.

During testing, if you want to update or restart some services (e.g : Django), you should follow the following steps:

docker compose stop django
docker compose rm django ## remove old django container
docker compose create django ## create new django container with the changes from your development
docker compose start django

This procedure helps you update changes of your development on Django without having to restart every Codabench container.

Give superuser privileges to a user

With superuser privileges, the user can edit any benchmark and can access the Django admin interface.

docker compose exec django ./manage.py shell_plus
u = User.objects.get(username='<USERNAME>') ## can also use email
u.is_staff = True
u.is_superuser = True
u.save()

Migration

docker compose exec django ./manage.py makemigrations
docker compose exec django ./manage.py migrate

Collect static files

docker compose exec django ./manage.py collectstatic --noinput

Delete POSTGRESDB and MINIO :

## Begin in codabench root directory
cd codabench

Purge data

sudo rm -r var/postgres/*
sudo rm -r var/minio/*

See data we are going to purge

ls var

Restart services and recreate database tables

docker compose down
docker compose up -d
docker compose exec django ./manage.py migrate

Feature competitions in home page

There are two ways of setting a competition as featured: 1. Use Django admin (see below) -> click the competition -> scroll down to is featured filed -> Check/Uncheck it 2. Use competition ID in the django bash to feature or unfeature a competition

docker compose exec django ./manage.py shell_plus
comp = Competition.objects.get(id=<ID>)  ## replace <ID> with competition id
comp.is_featured = True  ## set to False if you want to unfeature a competition
comp.save()

Shell Based Admin Features

If you're running your own Codabench instance, there are different ways to interact with the application. Inside the django container (docker compose exec django bash) you can use python manage.py help to display all available commands and a brief description. By far the most useful are createsuperuser and shell/shell_plus.

Django Admin interface

Once you log in an account with superuser privileges, you have access to the "Django Admin" interface:

From this interface, you can change a user's quota, change their staff and superuser status, change the featured competitions displayed on the homepage, manage user accounts and more.

Edit announcements

In the Django admin interface, click on Announcements:

Every announcement marked Is active is shown on the front page, inside the "Announcement" box. Each announcement has:

• Title (optional): shown in bold above the text.
• Level: controls the style.
  • Critical: red with an exclamation icon
  • Warning: yellow with a warning icon
  • Info: blue with an info icon
  • Plain: plain text with no background or icon
• Text: the body, written in HTML. Links are shown bold and underlined in the announcement's color.
• Is active: untick to hide an announcement without deleting it.
• Priority: controls the order. Lower numbers are shown first; announcements with the same priority are shown newest first.

You can create and edit announcements using the interface. Write the text using HTML to format it, add links, and more:

Edit news

In the Django admin interface, click on News posts:

All news objects are read by the front page as separate news. You can create and edit news using the interface. Write the news using HTML to format the text, add links, and more.

Delete a user

Go to Users:

Select it, select the Delete selected users action and click on Go:

Ban/Unban a user

Go to Users in the django admin:

Search for user using the search bar, or use the filter on the right side. Click on the username of the user to open user details, scroll down to find Is Banned. Check/uncheck this option to toggle the banned status.

RabbitMQ Management

The RabbitMQ management tool allows you to see the status of various queues, virtual hosts, and jobs. By default, you can access it at: http://<your_codalab_instance>:15672/. The username/password is your RabbitMQ .env settings for username and password. The port is hard-set in docker-compose.yml to 15672, but you can always change this if needed. For more information, see: https://www.rabbitmq.com/management.html

Change RabbitMQ username or password

RabbitMQ only reads RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS from .env the first time it starts with an empty data folder (var/rabbit). After that, the users are loaded from var/rabbit, so changing .env and restarting is not enough: RabbitMQ keeps the old credentials while the other services try the new ones, and the logs show login refused ... invalid credentials. docker compose down --volumes does not help either, because var/rabbit is a folder on the host, not a Docker volume.

Choose one of the two options below.

Option 1: New instance (RabbitMQ data can be deleted)

1. Update RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS in .env
2. Stop the services, delete the RabbitMQ data and start again:

docker compose down
sudo rm -rf var/rabbit
docker compose up -d

RabbitMQ starts empty and creates the user from .env.

Option 2: Instance in use (keep RabbitMQ data)

Use this when the platform is already in use. The RabbitMQ data is kept, and the new credentials are applied directly in RabbitMQ.

1. Update RABBITMQ_DEFAULT_USER and/or RABBITMQ_DEFAULT_PASS in .env
2. Recreate the containers so they use the new values:

docker compose up -d

At this point the workers cannot log in to RabbitMQ yet. This is expected and fixed by the next step.

1. Apply the new credentials in RabbitMQ. The commands read the new values from the rabbit container, so the password does not need to be typed.

If only the password changed:

docker compose exec rabbit sh -c 'rabbitmqctl change_password "$RABBITMQ_DEFAULT_USER" "$RABBITMQ_DEFAULT_PASS"'

If the username changed: create the new user and give it the same permissions as the old user. The old user has access to the main virtual host (/) and to the virtual host of every custom queue, so all of them are copied. Replace <old-username> with the previous RABBITMQ_DEFAULT_USER:

docker compose exec -e OLD_USER=<old-username> rabbit sh -c '
set -e
NEW_USER="$RABBITMQ_DEFAULT_USER"
rabbitmqctl add_user "$NEW_USER" "$RABBITMQ_DEFAULT_PASS"
rabbitmqctl set_user_tags "$NEW_USER" administrator
rabbitmqctl -q list_user_permissions "$OLD_USER" | tail -n +2 |
while IFS="$(printf "\t")" read -r vhost perm_configure perm_write perm_read; do
  rabbitmqctl set_permissions -p "$vhost" "$NEW_USER" "$perm_configure" "$perm_write" "$perm_read"
done
'

1. Restart the services that connect to RabbitMQ:

docker compose restart django site_worker compute_worker flower

1. Check that the services can log in. The rabbit logs should show user '<new-username>' authenticated and no login refused errors:

docker compose logs --since 2m rabbit | grep -E "authenticated|refused"

1. Update BROKER_URL on any compute worker running on another machine that connects to the default queue with these credentials (see Link compute workers to default queue). Workers on custom queues use their own RabbitMQ users and don't need any change.

docker compose exec rabbit rabbitmqctl delete_user <old-username>

Flower Management

Flower is a web based tool for monitoring and administrating Celery clusters. By default, you can access the Flower web portal at http://<your_codalab_instance>:5555/. The username/password is your Flower .env settings for username and password. 5555 is the default port, and cannot be changed without editing the docker-compose.yml file.

For more information on flower, please visit: https://flower.readthedocs.io/en/latest/

Storage analytics

The interface

The storage analytics page is accessible at codabench-url/analytics/ under the storage tab.

From this interface, you will have access to various analytics data:

• A Storage usage history chart
• A Competitions focused storage evolution, distribution and table
• A Users focused storage evolution, distribution and table

All of those data can be filtered by date range and resolution, and exported as CSVs.

The data displayed in those charts are only calculated from a background analytics task that takes place every Sunday at 02:00 UTC time (value editable in the src/settings/base.py).

The background task

The analytics task is a celery tasked named analytics.tasks.create_storage_analytics_snapshot. What it does:

• It scans the database looking for file sizes that are not set or flagged in error
• Actually measures their size and saves it in the database
• Aggregate the storage space used by day and by Competition/User (for example every day for the last year for each competition) by looking at the database file size fields
• For data related to the Platform Administration it measures as well the database backup folder directly from the storage instance.
• Everything is saved as multiple snapshot in time in each Category table (i.g.: UserStorageDataPoint)
• This tasks also runs a database <-> storage inconsistency check and saves the results in a log file located in the var/logs/ folder

To manually start the task, you can do the following:

• Start codabench docker compose up -d
• Bash into the django container and start a python console:
  Bash

  docker compose exec django ./manage.py shell_plus
  

• Manually start the task:
  Python

  from analytics.tasks import create_storage_analytics_snapshot
  eager_results = create_storage_analytics_snapshot.apply_async()
  

• If you check the logs (docker compose logs -f) of the app you should see "Task create_storage_analytics_snapshot started" coming from the site_worker container
• If you have to restart the task, don't worry, it will only compute the size of the files that hasn't been computed yet.
• Once the task is over you should be able to see the results on the web page

Homepage counters

There is also a daily background task counting users, competitions and submissions, in order to display it on the homepage.

You can manually run it:

docker compose exec django ./manage.py shell_plus

from analytics.tasks import update_home_page_counters
eager_results = update_home_page_counters.apply_async()

User Quota management

Increase user quota

Using the Django Shell

docker-compose exec django ./manage.py shell_plus

u = User.objects.get(username='<USERNAME>') ## can also use email
u.quota = u.quota * 3 # We multiply the quota by 3 in this example
u.save()

Using the Django Admin Interface

• Go to the Django admin page
• Click user table
• Select the user for whom you want to increase/decrease quota
• Update the quota field with new quota (in GB e.g. 15)

Codabench Statistics

You can create two types of codabench statistics:

• Overall platform statistics for a specified year
• Overall published competitions statistics

Follow the steps below to create the statistics

Start codabench

docker compose up -d

Bash into the django container and start a python console:

docker compose exec django ./manage.py shell_plus

For overall platform statistics

from competitions.statistics import create_codabench_statistics
create_codabench_statistics(year=2024)

For overall published competitions statistics

from competitions.statistics import create_codabench_statistics_published_comps
create_codabench_statistics_published_comps()