Installing Cyberismo

Card key

docs_17

Status

Draft

Card type

base/cardTypes/page

Labels

Owner

N/A

Information classification

public

There are a number of methods for installing Cyberismo locally, depending on the operating system and platform.

Prerequisite for all installation types

Install Git. While Cyberismo does not directly depend on Git, you will need it to manage Cyberismo content, such as when installing Cyberismo modules.

Method 1: Docker image from Docker Hub

For macOS and Linux, this is probably the easiest way to try out Cyberismo. For Windows, building the application locally from source is the recommended way, and it is not half as frightening as it sounds.

Prerequisites

The system must have Docker or a similar container environment installed, capable of running Linux-based images. The simplest way to install a container environment is to install Docker Desktop.

Downloading image from Docker Hub

The latest image can be downloaded with the following command:

$ docker pull cyberismo/cyberismo

Running

  • It is recommended to execute the following commands only within the Cyberismo root directory or within project directories.

  • To simplify running the image, you can use the following command (works only on Unix-based systems, not in Windows CMD or PowerShell):

    $ alias cyberismo="docker run --rm -it --user $(id -u):$(id -g) -v .:/project -p 3000:3000 cyberismo/cyberismo cyberismo"

The alias command allows you to execute the configured Docker environment with a single, simple command.

  • Flags in command:

    • -rm: Removes the container automatically after it exits.

    • -it: Runs the container in interactive mode.

    • --user: Container user will use the same user ID as the user executing the command. This will prevent file ownership problems.

    • -v: Maps the current execution directory to the /project directory inside the container, sharing files between host and container.

    • -p: Forwards the port from the container to the host machine, enabling access to the hosted web service.

  • Run the following command to view the command-line help:

    $ cyberismo --help

Method 2: Locally built Docker image

Prerequisites

The system must have Docker or a similar container environment installed, capable of running Linux-based images. The simplest way to install a container environment is to install Docker Desktop.

Building the container image

Take the following steps:

  1. Clone the source repository using one of the following methods:

    $ git clone git@github.com:CyberismoCom/cyberismo.git # SSH
$ git clone https://github.com/CyberismoCom/cyberismo.git # HTTPS

  2. Change to the source directory. If you have already cloned the repository earlier, remember to pull the latest changes:

    $ cd cyberismo
$ git pull origin main # Optional

  3. Execure the following commands:

    $ docker build -t cyberismo .

  4. Once the build has finished, you can verify the existence of the built image with the following command:

    $ docker images

Running

  • It is recommended to execute the following commands only within the Cyberismo root directory or within project directories.

  • To simplify running the image, you can use the following command (works only on Unix-based systems, not in CMD or PowerShell):

    $ alias cyberismo="docker run --rm -it --user $(id -u):$(id -g) -v .:/project -p 3000:3000 cyberismo cyberismo"

The alias command allows you to execute the configured Docker environment with a single, simple command.

  • Flags in command:

    • -rm: Removes the container automatically after it exits.

    • -it: Runs the container in interactive mode.

    • --user: Container user will use the same user id as the user executing the command. This will prevent file ownership problems.

    • -v: Maps the current execution directory to the /project directory inside the container, sharing files between host and container.

    • -p: Forwards the port from the container to the host machine, enabling access to the hosted web service.

  • Run the following command to view the command-line help:

    $ cyberismo --help

Method 3: Building and running Cyberismo locally from source

Prerequisites

Common prerequisites

Install Node.js. The currently supported Node.js version is the latest LTS, v20.10.0. Node.js is downloadable from https://nodejs.org/.

Windows and macOS

When building Cyberismo on Windows, the system automatically installs the required dependencies (Clingo and libraries) using a prebuilt package by Cyberismo.

When building Cyberismo on macOS, there is a utility script which you can use to install a minimal Python distribution Miniconda and the required dependencies under the vendor directory in the Cyberismo main directory. Instructions are provided below.

Linux

Installing the required dependencies automatically on Linux is a work in progress. Take the following steps:

  1. Install Clingo. The currently supported Clingo version is 5.7.1. We recommend installing a Python-enabled build using Anaconda, as instructed in https://github.com/potassco/clingo/releases/.

  2. Install the latest version of Clingraph.

Building

Take the following steps:

  1. Clone the source repository using one of the following methods:

    $ git clone git@github.com:CyberismoCom/cyberismo.git # SSH
$ git clone https://github.com/CyberismoCom/cyberismo.git # HTTPS

  2. Change to the source directory. If you have already cloned the repository earlier, remember to pull the latest changes:

    $ cd cyberismo
$ git pull origin main # Optional

  3. Execute the following commands:

    $ pnpm setup
$ pnpm install
$ pnpm build
$ pnpm link -g
On Windows, the required dependencies are installed automatically. On macOS, you can install the dependencies with 
$ pnpm install-dev-packages

Running

After building and installing, run cyberismo --help to see the command line help.