Installation
The easiest way to install CIRCUS is to use the official Docker image hosted on Docker Hub.
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:latestInitial Configuration#
To prepare the initial data needed to start CIRCUS, take the following steps:
-
Create the directory
/var/circus/dataon your host machine. -
Create a CIRCUS container and run
/bin/bashinside 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
-hoption. Here it iscircus, 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
-poption) or map IP addresses (with--add-host).
- You don't need to manually specify
-
Inside the created container, run the following command to initialize the database.
Inside the container# /circus/data_initialization.sh -
Type
exitinside 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:latestIt 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:
# /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:latestTo stop this container, inspect its ID using docker ps, and run docker kill --force <container-id>.
Check if the Server is Running#
-
After starting CIRCUS as described above, access http://localhost/ (or http://127.0.0.1/) using a web browser on the host machine.
-
When the login screen appears, enter "circus" for both the user name and password.
-
If the CIRCUS home screen appears, you have successfully logged in.
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.
# cd /var/circus/packages/circus-api
# node circus migrateBacking 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.shThe dumped data will be created at /var/circus/data/mongodb_dump/circus_mongo_archive_[timestamp].gz.