Skip to main content

Using dorcha-gateway on Linux

We provide tar archives containing Linux binaries for dorcha-gateway. Our binaries currently support the following operating systems:

  • Ubuntu 18.04 LTS (Bionic Beaver) and above
  • Amazon Linux 2
  • Red Hat Enterprise Linux 8 and above
  • Debian 11 Bullseye and above

Prerequisites​

  • Linux system with one of the supported distributions
  • Root or sudo access for installation
  • At least 512MB RAM
  • Network access for configuration and updates

Installation​

Option 1: System-wide Installation​

# Move to system bin directory
sudo mv dorcha-gateway /usr/local/bin/
sudo chmod +x /usr/local/bin/dorcha-gateway

# Verify installation
dorcha-gateway --version

Option 2: User Installation​

# Move to user bin directory
mkdir -p ~/.local/bin
mv dorcha-gateway ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Configuration​

  1. Create configuration directory:
sudo mkdir -p /etc/dorcha
sudo mkdir -p /var/log/dorcha
sudo mkdir -p /var/lib/dorcha/keys
  1. Copy example configuration:
sudo cp example-configs/config.http.example.json /etc/dorcha/dorcha-gateway-config.json
sudo nano /etc/dorcha/dorcha-gateway-config.json

Running as a Service​

Systemd Service​

Create /etc/systemd/system/dorcha-gateway.service:

[Unit]
Description=Dorcha Gateway
After=network.target

[Service]
Type=simple
User=dorcha
ExecStart=/usr/local/bin/dorcha-gateway -config /etc/dorcha/dorcha-gateway-config.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Create the dorcha user:

sudo useradd -r -s /bin/false dorcha
sudo chown -R dorcha:dorcha /etc/dorcha /var/log/dorcha /var/lib/dorcha

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable dorcha-gateway
sudo systemctl start dorcha-gateway

Verification​

Check if the service is running:

sudo systemctl status dorcha-gateway
curl http://localhost:3128/health

View logs:

sudo journalctl -u dorcha-gateway -f

Troubleshooting​

Common Issues​

  • Permission denied: Ensure the binary is executable
  • Port already in use: Check if port 3128 and 3129 are available
  • Configuration errors: Validate JSON syntax in config file

Logs​

  • Service logs: sudo journalctl -u dorcha-gateway
  • Application logs: /var/log/dorcha/