8. Management Tasks

8.1. Create a new superuser

In case you are locked out because you have forgotten the

1. Login to the shell of your Agora server by an SSH session (if you have lost the SSH password, we can’t help you)

2. Make sure Agora is running

sudo docker ps

CONTAINER ID        IMAGE                                              COMMAND                  CREATED             ....     NAMES
xxxxxxxxxxx         gtagora-registry.gyrotools.com/gtagora/app:5.2.0   "/entrypoint.sh"         3 weeks ago         ....     agora_app
xxxxxxxxxxx         gtagora-registry.gyrotools.com/gtagora/web:5.2.0   "/entrypoint.sh"         3 weeks ago         ....     agora_web
xxxxxxxxxxx         postgres:9.6                                       "docker-entrypoint.s…"   3 weeks ago         ....     agora_db
xxxxxxxxxxx         redis:3.0                                          "docker-entrypoint.s…"   5 weeks ago         ....     agora_redis

3. Enter the agora_app container

sudo docker exec -it agora_app bash

root@f5bf25337c86:/app#

4. Create a new superuser

python /app/srv/manage.py createsuperuser

5. Open Agora in the browser and login with the newly created user. Now your can’t set a new password for your all account.

Caution

Don’t run the python command by calling docker’s “run” command (sudo docker run -it agora_app ...). This will start a new Agora instance.

8.2. Agora management commands

If Agora is running, you can execute the built-in Agora management tool from the host with:

sudo gtagora manage <command> [arguments]

This is a shortcut for running the same command inside the application container:

python /code/manage.py agora <command> [arguments]

The following top-level commands are available:

Command	Description
anon	Anonymization tools, including repair of partially anonymized exams.
check	Data consistency checks, for example validation of datafiles.
cleanup	Cleanup tasks for temporary directories, trash, zombie files, and similar leftovers.
export	Export Agora elements such as projects, folders, exams, series, and datasets.
image	Image information tools for inspecting failed entries and updating outdated image info.
import	Import Agora export archives (.aex).
license	License tools to check, activate, renew, or inspect the current license.
logfile	Log file utilities, including nginx log access configuration and traffic parsing.
parameter	Parameter maintenance tools to store, compress, restore, clean up, and refresh parameter names.
project	Project utilities to display project structure and print or update project statistics.
root_path	Manage root paths and generate Apache or nginx configuration for them.
thumbnail	List existing thumbnails or create missing thumbnails.
timeline	Timeline maintenance tools, including finishing timeline items in bulk.
transfer	Transfer exams, series, datasets, or folders to another Agora instance.
user	Create the default admin account.
version	Show the current Agora version.

The sections below summarize the subcommands that are currently exposed by python manage.py agora.

8.2.1. Command reference

8.2.1.1. parameter

Parameter maintenance tools.

• parameter store

  Store parameters from the database to files and reload queued parameter data into the database.

  Options:

  • --reset-status-error resets the error status of erroneous datasets.

  • --reset-status-all resets the error status of all datasets.

  • --force recreates parameter files even if they already exist.

  • --file-only only stores parameters to files.

  • --no-file only reloads parameters into the database.

• parameter compress

  Save parameter data to files and compress parameter sets in the database to a minimal format.

• parameter restore

  Restore full parameter sets in the database from the stored parameter files.

• parameter cleanup

  Clean up the parameter database, including duplicate collections and multi-page parameter sets.

  Options:

  • --dry-run reports affected parameter collections without changing the database.

• parameter update-names

  Update stored parameter names for search intellisense.

8.2.1.2. version

Show the current Agora version.

Options:

• --all prints the version, build time, and changeset.

• --write writes the current version information to the database.

8.2.1.3. root_path

Manage configured root paths and generate web server configuration for them.

• root_path list

  Show all configured root paths.

• root_path create <path>

  Create a new root path.

• root_path update <root_path_id> [--path <path>] [--active <true|false>]

  Update the location or active state of an existing root path.

• root_path delete <root_path_id>

  Delete a root path.

• root_path apache [path]

  Generate Apache configuration for the configured root paths.

• root_path nginx [path]

  Generate nginx configuration for the configured root paths.

8.2.1.4. user

Create the default admin account.

• user create_default_admin

  Create the default admin user, or set the default password when the account already exists without a password.

  Options:

  • --force sets the default password even when the admin user already exists.

8.2.1.5. license

License maintenance tools.

• license check

  Check the current license.

  Options:

  • --local checks only the local key.

• license activate <activation_code>

  Activate a license with the supplied activation code.

• license renew

  Renew the current local license key.

  Options:

  • --force forces a renewal attempt.

• license current

  Show the current license.

• license activationfile

  Generate the activation file content.

8.2.1.6. logfile

Log file utilities.

• logfile nginx <path>

  Write an nginx configuration that exposes the Agora log files.

  Options:

  • --dry-run prints the generated configuration without writing it.

• logfile parse-traffic <outfile>

  Extract HTTP request traffic from the log files for later analysis.

8.2.1.7. cleanup

Run cleanup jobs for temporary directories, old trash elements, zombie files, and similar leftovers.

Options:

• --dry-run reports actions without deleting anything.

• --delete-zombies includes zombie cleanup jobs that are otherwise skipped.

• --move-zombie-files moves zombie files instead of deleting them.

8.2.1.8. anon

Anonymization tools.

• anon repair

  Find and repair partially anonymized exams.

  Options:

  • --project-id <id> restricts the repair to a single project.

  • --yes or -y skips the confirmation prompt.

  • --verbose or -v prints a detailed summary of affected exams.

8.2.1.9. image

Image information tools.

• image info update

  Update all outdated image information entries.

• image info failed

  List failed image information entries.

  Options:

  • --copy-files <path> copies the related files to the given directory.

8.2.1.10. timeline

Timeline maintenance tools.

• timeline finish_all

  Mark started timeline items as finished.

  Options:

  • --project-id <id> processes timeline items for a single project.

  • --user-id <id> processes timeline items for a single user.

  At least one of --project-id or --user-id must be supplied.

8.2.1.11. thumbnail

Thumbnail management tools.

• thumbnail list --all

• thumbnail list --exam <id>

• thumbnail list --series <id>

• thumbnail list --dataset <id>

  List thumbnail paths for all thumbnails or for a selected exam, series, or dataset.

• thumbnail create --all [--force]

• thumbnail create --exam <id> [--force]

• thumbnail create --series <id> [--force]

• thumbnail create --dataset <id> [--force]

  Create missing thumbnails, or recreate them with --force.

8.2.1.12. export

Export Agora objects to .aex archives.

• export project <id>

• export exam <id>

• export series <id>

• export dataset <id>

• export folder <id>

  Export the selected object.

  Common options:

  • --outdir <path> sets the output directory.

  • --no-data exports metadata only.

  • --indent <n> sets the JSON indentation level.

  • --compress compresses the export file.

  • --password <password> encrypts the export file.

8.2.1.13. import

Import Agora export archives.

• import <filename>

  Import a .aex, .aex.gz, .aex.enc, or .aex.gz.enc archive.

  Options:

  • --project <id> imports into the selected project.

  • --project-name <name> overrides the imported project name.

  • --folder <id> imports into the selected folder.

  • --user <id> imports as the selected user id.

  • --username <name> imports as the selected username.

  • --dry-run validates the archive without importing it.

  • --force imports even if the data already exists.

  • --password <password> decrypts an encrypted archive.

  Automatic schema migration

  Each .aex archive records the AEX schema version and the set of Django migrations that were applied when it was created. When importing an archive that was exported from an older version of Agora, the import pipeline automatically replays the relevant schema changes (added fields, removed fields, renamed fields and models) against the JSON data inside the archive before handing it to the normal import logic. This means archives created with earlier versions of Agora can be imported without manual intervention.

  The following migration operations are applied automatically:

  • AddField — missing fields are filled with the field’s default value or null.

  • RemoveField — keys not present in the current schema are stripped.

  • RenameField / RenameModel — keys and filenames are updated to match the current names.

  Operations involving arbitrary Python or SQL (RunPython, RunSQL) cannot be replayed automatically and are skipped with a warning. If a migration of this type affects data that is present in AEX archives, a manual AEX migration must be provided in the Agora source.

8.2.1.14. project

Project maintenance tools.

• project statistics update

  Update project statistics.

  Options:

  • --id <project_id> limits the update to one project.

  • --only-outdated only updates outdated statistics.

• project statistics print

  Print project statistics.

  Options:

  • --id <project_id> limits output to one project.

  • --outfile <path> writes the statistics as JSON.

  • --light prints a faster, reduced version of the statistics.

• project display <project_id>

  Print the folder and exam structure of a project on the command line.

  Options:

  • --depth <n> limits the folder tree depth.

8.2.1.15. check

Consistency checks for stored data.

• check datafiles

  Check whether referenced datafiles exist on disk and report zombie datafiles.

  Options:

  • --no-zombies skips the zombie datafile check.

  • --no-files skips the on-disk file existence check.

8.2.1.16. transfer

Transfer Agora objects to another Agora instance.

• transfer exam <id> <url> <target-project-id>

• transfer series <id> <url> <target-project-id>

• transfer dataset <id> <url> <target-project-id>

• transfer folder <id> <url> <target-project-id>

  Transfer the selected object to another Agora instance and target project.

  Common options:

  • --api-key <key> authenticates with an API key.

  • --username <name> authenticates with a username.

  • --password <password> authenticates with a password.

  • --target-path <path> places the transferred object below the given target path on the destination instance.