Skip to content

Installation and Setup of GitFlic Runner with Docker Type

Check the compatibility table for the required agent version and download it from the runner releases page. The latest runner version is available here.

Dependency Installation

  1. Install the required Docker Engine version 

    sudo apt update && sudo apt install docker.io

    1.1 Remove conflicting packages 

    ```shell  
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done  
```

    1.2 Set up Docker repository 

    ```shell  
# Add Docker's official GPG key:  
sudo apt-get update  
sudo apt-get install ca-certificates curl  
sudo install -m 0755 -d /etc/apt/keyrings  
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc  
sudo chmod a+r /etc/apt/keyrings/docker.asc  

# Add the repository to Apt sources:  
echo \  
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \  
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \  
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null  
sudo apt-get update  
```

    1.3 Install Docker packages 

    ```shell  
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin  
```

    Follow Docker's official installation guide.

  2. Install Java

    • Check available OpenJDK versions: 
    sudo apt policy openjdk-11-jdk
    • Install the package: 
    sudo apt install openjdk-11-jdk
    • Verify installation: 
    java --version
    • Copy Axiom JDK deb package to remote server 
    scp axiomjdk11-*.deb <username>@<ip>:~/
    • Install the package: 
    sudo apt install ./axiomjdk11*.deb
    • Verify installation: 
    java --version

Agent Installation

  • Run installation script 

    echo "deb [signed-by=/etc/apt/keyrings/gitflic.asc] https://registry.gitflic.ru/company/gitflic/package/-/deb main stable" | sudo tee -a /etc/apt/sources.list.d/gitflic.list  
sudo curl https://registry.gitflic.ru/company/gitflic/package/-/deb/dists/main/public-key.asc -o /etc/apt/keyrings/gitflic.asc  
sudo apt update && sudo apt install gitflic-runner -yq

  1. Create temp directory and extract runner package 

    sudo mkdir /tmp/gitflic-runner  
sudo unzip runner_*.zip -d /tmp/gitflic-runner

  2. Create directory for runner.jar 

    sudo mkdir -p /opt/gitflic-runner

  3. Copy runner.jar to target directory 

    sudo cp /tmp/gitflic-runner/runner.jar /opt/gitflic-runner

  4. Create gitflic-runner user 

    sudo useradd --no-create-home --system --shell /sbin/nologin gitflic-runner

  5. Add gitflic-runner to docker group 

    sudo usermod -aG docker gitflic-runner

Agent Registration

  1. Access web interface

    GitFlic → Admin Panel → CI/CD 

    http(s)://<Web Interface Address>/admin/runners

    Agent registration on gitflic.ru is only available at company level

    Company Settings → CI/CD Agents 

    https://gitflic.ru/company/<company_name>/setting/cicd/runners

  2. Copy and save URL and Token

    Get Token

  3. Navigate to runner.jar directory 

    sudo cd /opt/gitflic-runner

  4. Run registration command 

    sudo java -jar runner.jar register --url <url> --registration-token <token>
    Parameter Required Description
    --url <url> Yes URL copied in step 1
    --registration-token <token> or --token <token> Yes Token copied in step 1
    --name <name> No Agent name
    --tags <tags> No Agent tags (comma-separated)
    --registry-url <docker_registry_url> No Docker registry URL (required for private registry access)
    --registry-user <docker_registry_user> No Docker registry username (required for private registry access)
    --registry-password <docker_registry_password> No Transport token for registry auth (required for private registry access)
    --docker-image <image> No Default image when none specified in pipeline
    • Upon successful registration, the web interface will show the connected agent.
    • A config directory containing application.properties will be created.

    Agent Registration

  5. Add required parameters to config/application.properties: 

    runner.executor=docker  
docker.didEnable=false  
docker.host=unix:///var/run/docker.sock  
docker.registry-username= #Registry username  
docker.registry-password= #Registry password  
docker.registry-url= #Registry URL  
logging.file.name=data/log/server.log  
logging.level.root=INFO

    Add additional parameters as needed. See parameter reference.

  6. Set directory ownership 

    sudo chown -R gitflic-runner:gitflic-runner /opt/gitflic-runner

Windows Docker Socket Path

For Windows Docker hosts, use npipe interface: 

docker.host=npipe:////./pipe/docker_engine

Docker Hub Alternative

Due to Docker Hub limitations, configure GitFlic Docker Registry in config/application.properties: 

docker.registry-username= #gitflic.ru username  
docker.registry-password= #gitflic.ru transport token  
docker.registry-url=https\://registry.gitflic.ru

Legacy Agent Support (<3.1.1)

For older agents, add these parameters to handle helper image: 

runner.helperImage=registry.gitflic.ru/company/gitflic/gitflic-runner-helper:{agent version}  
docker.registry-username= #gitflic.ru username  
docker.registry-password= #gitflic.ru transport token  
docker.registry-url=https\://registry.gitflic.ru

Agent Startup

Run startup command 

sudo -u gitflic-runner java -jar runner.jar start --config=config/application.properties

--config= specifies configuration file location.

  1. Create systemd unit file 

    touch /etc/systemd/system/gitflic-runner.service

  2. Add service configuration 

    sudo cat <<EOF >> /etc/systemd/system/gitflic-runner.service  
[Unit]  
Description=Gitflic-runner  

[Service]  
User=gitflic-runner  
Group=gitflic-runner  
WorkingDirectory=/opt/gitflic-runner  
ExecStart=/usr/bin/java -jar runner.jar start --config=config/application.properties  
ExecStop=/bin/kill -s 15 $MAINPID  
StandardOutput=journal  
StandardError=journal  
Restart=on-failure  
RestartSec=10  
TimeoutStartSec=2min  

[Install]  
WantedBy=multi-user.target  
EOF
    /etc/systemd/system/gitflic-runner.service 
    [Unit]  
Description=Gitflic-runner  

[Service]  
User=gitflic-runner  
Group=gitflic-runner  
WorkingDirectory=/opt/gitflic-runner  
ExecStart=/usr/bin/java -jar runner.jar start --config=config/application.properties  
ExecStop=/bin/kill -s 15 $MAINPID  
StandardOutput=journal  
StandardError=journal  
Restart=on-failure  
RestartSec=10  
TimeoutStartSec=2min  

[Install]  
WantedBy=multi-user.target

  3. Reload systemd 

    sudo systemctl daemon-reload

  4. Enable and start service 

    systemctl enable gitflic-runner.service  
systemctl start gitflic-runner.service

Automatic Translation!

This page has been translated using automated tools. The text may contain inaccuracies.