Skip to main content

Installation

The easiest way to install CIRCUS is to use the official Docker image hosted on Docker Hub.

info

As of July 2022, CIRCUS has not been tested on Docker running on macOS.

Download and Configure CIRCUS Docker Image​

The following steps assume that the CIRCUS data folder (the directory that will contain all persistent data on the host machine) is /var/circus/data. You can change this to any directory. For example, if your host machine is Windows and you want to set the data folder as C:\circus\data, replace the following /var/circus/data with /c/circus/data. Please choose a directory that does not affect the operation of the host machine and the Docker container.

Install Docker​

Install Docker on the machine where CIRCUS will be installed. Refer to the official Docker documentation for details.

  • Linux: docker-ce 19.03 or later
  • Windows: Docker Desktop for Windows

Fetch CIRCUS Docker Image​

Download the following Docker images from Docker Hub:

$ sudo docker pull circuscad/circus:latest
$ sudo docker pull circuscad/dicom_utility:latest
tip
  • The latest tag refers to the latest recommended version, which may change without notice. For long-term operation, consider fixating the version instead of using latest.
  • The latest version of CIRCUS can be viewed on the following URL: https://hub.docker.com/u/circuscad
note

Remove sudo when you are using Windows.

Initial Configuration​

To prepare the initial data needed to start CIRCUS, take the following steps:

  1. Create the directory /var/circus/data on your host machine.

  2. Create a CIRCUS container and run /bin/bash inside the container.

    $ sudo docker run --rm -v /var/circus/data:/var/circus/data \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -h circus -it circuscad/circus:latest
    • You don't need to manually specify /bin/bash; it will run automatically when you attach to the container.
    • Set the hostname of the container with the -h option. Here it is circus, but you can use another name. Note thet the container may not work correctly if you change the hostname each time you start a container.
    • During this initial setup, you don't have to expose a port (with the -p option) or map IP addresses (with --add-host).

  3. Inside the created container, run the following command to initialize the database.

    Inside the container
    # /circus/data_initialization.sh

  4. Type exit inside the attached shell to finish the container.

Running Commands Within a Container​

Sometimes, a CIRCUS administrator needs to access /bin/bash within the container to issue some administrative CLI commands.

  • To initialize or migrate the database
  • To register a CAD plug-in
  • To run other administrative tasks or utilities offered only as CLI
  • To bulk-import a large amount of DICOM data set

To access Bash within a CIRCUS container, type the following command (from the host machine):

$ sudo docker run --rm -v /var/circus/data:/var/circus/data \
  -v /var/run/docker.sock:/var/run/docker.sock -p 80:8000 -p 27017:27017 \
  -h circus --add-host=hostmachine:[IP address for host] \
  -it circuscad/circus:latest
note
  • The internal web server will be exposed to the host port 80.
  • You can remove -p 27017:27017 if you don't plan to manage database via external Mongo Shell.
  • The -v /var/run/docker.sock:/var/run/docker.sock option is used to allow CIRCUS to access plug-ins using the Docker outside of Docker (DooD) technique.
  • Replace [IP address for host] with the host IP address, which can be discovered using commands of each OS. For example:
    • ip a (Ubuntu)
    • ipconfig (Windows)

It is recommended to register the above script to a Bash alias, etc.

For details of the CLI, see this guide.

Starting CIRCUS Up​

Manual Startup From Within the Container​

Attach to Bash in the container as described above, and run the following:

Inside the container
# /circus/services.sh &

Starting CIRCUS as a Daemon​

The following command will start the Docker container in the background and automatically start the servers (this is using -d -e DAEMON_MODE=1 instead of -it).

$ sudo docker run --rm -v /var/circus/data:/var/circus/data \
  -v /var/run/docker.sock:/var/run/docker.sock -p 80:8000 -p 27017:27017 \
  -h circus --add-host=hostmachine:[IP address for host] \
  -d -e DAEMON_MODE=1 circuscad/circus:latest

To stop this container, inspect its ID using docker ps, and run docker kill <container-id>.

Check if the Server is Running​

  1. After starting CIRCUS as described above, access http://localhost/ (or http://127.0.0.1/) using a web browser on the host machine.

  2. When the login screen appears, enter "circus" for both the user name and password.

  3. If the CIRCUS home screen appears, you have successfully logged in.

danger
  • circus is the initial user with all administrative privileges. After the first logging-in, make sure to change its password to a safe one following the steps described in User Settings. Otherwise, everyone will be able to log in as an administrator with the default password!
  • A safer approach is to make a new user with a unique login ID and a safe password, make it belong to the admin group, and disable the default circus user.

For the overview of the user management, refer to Privilege System.

Upgrading the Docker Image​

When you use a newer version of our Docker image, you may need to perform a database migration. Attach to Bash as described above, and run the following command to upgrade the structure of the database.

Inside the container
# cd /var/circus/packages/circus-api
# node circus migrate
danger

This operation is irreversible. Once the database revision has been increamented by this operation, you can no longer use the previous version of the Docker image. Please take extra precautions such as backing up the internal database (MongoDB) beforehand.

Backing Up Data​

All persistent data will be stored in the host /var/circus/data directory (or any other directory you specify when you create the container with the -v option). This directory will contain the following types of data:

  • MongoDB database (most non-binary data such as user information, case information)
  • Uploaded DICOM series data
  • Binary data such as CIRCUS DB voxel labels
  • Plug-in results from CIRCUS CS
  • Various logs

Backups can be made by simply copying these files to elsewhere.

Dumping the MongoDB data​

After starting CIRCUS inside the CIRCUS Docker container, you can perform a dump (binary backup) of the internal database by running the following command.

# /circus/mongodb_dump.sh

The dumped data will be created at /var/circus/data/mongodb_dump/circus_mongo_archive_[timestamp].gz.