genroc

    docs / Guides / Getting started

    Installation

    Get genctl, start a project and run genroc in docker.

    The CLI

    Install genctl by running the following command in your terminal:

    curl -fsSL https://genroc.org/install.sh | sh -s

    This puts the genctl binary in /usr/local/bin if you can write there, otherwise in ~/.local/bin (set GENROC_INSTALL_DIR to choose). If that folder isn't on your PATH, the script warns you; add it before you continue.

    Starting a project

    Once you install genctl, you can create your first project with the init command (we assume you accept the defaults it offers):

    genctl init

    Enter the project folder:

    cd genroc-app

    Open the project in your editor. With the default options it looks like this:

    genroc-app/
    ├─ data/                   # the database, once the server starts
    ├─ definitions/
    │  └─ hello.genroc.yaml    # the example process definition
    ├─ .genroc                 # genctl project file: where your definitions are
    ├─ compose.yaml            # docker compose file for starting the server
    └─ .gitignore

    Editor support

    If you use VS Code, we recommend installing genroc extension. It provides language support for *.genroc.yaml files.

    Running with docker

    To continue you need to have docker installed on your system.

    The following command starts the containers:

    docker compose up -d

    Genroc listens on port 8448, which is where genctl looks for it by default, so it should now work:

    > genctl instances
    no instances

    Should run without an error.

    Stop it with docker compose down; your data stays in the data folder.

    The default setup has no authentication, anyone on your network can run code through it. Turn it on with genctl init --auth in a new project (Authentication for an existing one), and see Running in production before running genroc anywhere but your laptop.

    data folder

    Our example project stores database files in the data folder. This folder is in .gitignore by default.

    Genroc runs as its own user in the container, so genctl init makes the folder writable for everyone. On Linux, a folder Docker creates itself is owned by root and genroc can't write to it, so to prune the database delete the files, not the folder:

    docker compose down
    rm data/genroc.db*
    docker compose up -d

    After a fresh clone of the project on Linux, create the folder with mkdir -m 777 data.

    Uninstalling

    To uninstall genctl:

    curl -fsSL https://genroc.org/install.sh | sh -s -- --uninstall

    To also delete your settings (config directory), add --purge:

    curl -fsSL https://genroc.org/install.sh | sh -s -- --uninstall --purge