5. Post installation tasks¶

5.1. License¶

To activate Agora, login as an administrator and navigate to Settings -> License. Click on Add new License and copy the activation code into the provided text field. The activation token is provided by GyroTools and sent via email after purchasing Agora.

Important

No activation code? Create an account on https://portal.gyrotools.com/portal/ and contact us for obtaining a license.

5.2. Email Settings¶

Agora sends emails in many situations to users and administrators. To avoid that these emails are treated as spam, it is recommended to use your institution’s email server. Ask your IT for assitance. You need the server address, port, and most likely authentication credentials.

5.3. Hostname¶

Go to Settings -> Server and add the hostname of the server. This is important for the correct generation of links in emails (e.g. password reset links). The hostname is also available as variable in the task definition.

5.4. Dicom Node¶

Agora is also a Dicom node. It can receive Dicom images from other nodes such as a PACS. In order to setup a Node on the sending side, you need to provide AETitle and the port of the Agora Dicom node. You find this information on the info page in the Agora settings.

5.5. Webserver Certificate¶

By default the Agora installer creates a self-signed server certificate. This is not optimal as the Agora users will have to accept this self-signed certificate. It’s better to use a signed certificate. Ask your IT for asstistance in obtaining such a certificate.

Agora stores the key and the certificate on the agora_nginx volume. Just replace the existing files and restart the agora_web container.

sudo docker volume inspect agora_nginx

[
    {
        "CreatedAt": "201xxxxxxxxx",
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/agora_nginx/_data",
        "Name": "agora_nginx",
        "Options": {},
        "Scope": "local"
    }
]

ls -la /var/lib/docker/volumes/agora_nginx/_data

 .
 ..
agora.cert
agora.key
nginx-agora-paths

# replace agora.cert and agora.key

sudo docker restart agora_web

5.6. Global Hosts¶

Optionally, agora system administrators can define global host servers. Agora users then can import such a host into their projects and use them as task execution hosts. To define global hosts go to settings -> hosts and select the ‘create new host’ button. Set the host server type to ‘ssh’, provide the server details and the credentials. Note that any user with task execution privileges will be able to use the defined host. Host and accounts that should not be used by all Agora users have to be defined by the users in the respective project settings.

5.7. Useful Docker commands¶

Show all running docker processes:

sudo docker ps

Pull latest Agora Docker container:

sudo docker-compose -f /etc/gyrotools/agora/config.json pull

Delete unused Docker images (eg after version upgrade, stop running container first):

docker image prune

Docker volume management:

docker volume ...

5.8. Setup an SSH Task Container¶

5.8.1. Overview¶

This guide explains how to set up a dedicated SSH-enabled Docker container for running tasks on your Agora server. This is useful when you lack SSH access to an external workstation and want to run tasks directly on the Agora host.

The task container provides:

Isolation - Separates task execution from the main Agora server
Customization - Install tools and packages without affecting the Agora host
Security - Enhanced security through containerization
Easy setup - Runs alongside existing Agora containers without configuration changes

You can run an SSH-enabled task runner container alongside Agora by declaring it in config.json under addons. The installer will then render it into docker-compose.yml and start it with the other Agora services. This avoids manual Dockerfile builds and separate docker run commands.

Note

This guide uses Docker commands, but the same approach works with Podman. Simply replace docker with podman in all commands.

5.8.2. Architecture¶

┌─────────────────────┐         ┌──────────────────────┐
│ Agora App Container │         │  SSH Task Container  │
│                     │         │                      │
│   - Task Engine     │────────▶│   - SSH Server       │
│   - SSH Client      │  SSH    │   - Task Runtime     │
│                     │         │   - User Environment │
└─────────────────────┘         └──────────────────────┘
           │                              │
           └──────────────────────────────┘
            Existing Docker Network

5.8.3. Example config snippet¶

Add this to your config.json:

"addons": [
  {
    "name": "task-runner",
    "image": "gyrotools/agora-task-runner:latest",
    "environment": {
      "USERNAME": "runner",
      "PASSWORD": "secret123",
      "UID": "1001",
      "GID": "1001",
      "SSH_PORT": "22"
    },
    "expose": ["22"],
    "healthcheck": {
      "test": ["CMD-SHELL", "nc -z localhost 22"],
      "interval": "10s",
      "timeout": "5s",
      "retries": 5
    }
  }
]

gyrotools/agora-task-runner:latest is a ready-to-use container provided by GyroTools with an SSH server installed and the following Python packages:

scipy
numpy
requests
psutil
gtagora-connector

Alternatively, you can use any custom image with an SSH server or build your own using the Dockerfile template from the GyroTools/agora-task-runner GitHub repository. If you need additional Python packages, you can either build a custom image using the Dockerfile in the repository or install them at runtime via your tasks.

5.8.4. Key points¶

Credentials: Set USERNAME and PASSWORD to your desired SSH login. Change the defaults before use.
UID/GID: Override if you need to match host or volume permissions.
Expose: Using expose opens the ssh port within the Agora docker network.
Healthcheck: Included to let Compose report readiness.

5.8.5. How to apply¶

Update config.json with the addons block above.
Rebuild the docker-compose.yml with
sudo gtagora rebuild
Restart Agora with:
sudo gtagora start

5.8.6. Connecting from Agora¶

In Agora, define a Host with:

Name: task-runner
Type: SSH
Host: task-runner
Port: 22 (or whatever you set in SSH_PORT)
Auth: Username/Password
Username: value of USERNAME (e.g., runner)
Password: value of PASSWORD (e.g., secret123)
Working Directory: e.g., /home/runner or whatever you have chosen as user home

5.8.7. Connecting from within the Agora app container¶

If you need to test connectivity from within the Agora app container, first go into the app container shell:

sudo docker exec -it agora_app bash

Then SSH to the task runner:

ssh runner@task-runner

5.8.8. Optional: publish to host¶

If you need host access for debugging, add a port mapping: .. code-block:: json

“ports”: [“2222:22”]

Then SSH from the host with: .. code-block:: bash

ssh runner@localhost -p 2222

5.8.9. Troubleshooting¶

Check container logs: docker compose logs task-runner (service name in your compose).
Verify healthcheck: ensure the service reports healthy in docker ps.
Network resolution: from the app container, ssh runner@task-runner (no host publish required).
Credential issues: ensure PASSWORD is set and not empty; rebuild/restart if changed.