Manual Installation

Build and deploy Rexec from source without Docker Compose

Overview

This guide covers installing Rexec manually without Docker Compose. This approach gives you more control and is useful for:

• Development environments
• Custom deployment setups
• Environments where Docker Compose isn’t available
• Integration with existing infrastructure

Prerequisites

1. Install Go 1.24+

   # Check Go version
   go version
   

   Install from https://go.dev/dl/

2. Install Node.js 22+

   Required for building the frontend:

   node --version
   npm --version
   

   Install from https://nodejs.org/

3. Install Docker Engine

   Rexec requires access to a Docker daemon:

   docker --version
   

   Install from https://docs.docker.com/engine/install/

4. Install PostgreSQL 16+

   # Ubuntu/Debian
   sudo apt install postgresql postgresql-contrib
   
   # macOS
   brew install postgresql@16
   
5. Install Redis 7+

   # Ubuntu/Debian
   sudo apt install redis-server
   
   # macOS
   brew install redis
   

Database Setup

1. Create PostgreSQL Database

   # Start PostgreSQL service
   sudo systemctl start postgresql  # Linux
   brew services start postgresql@16  # macOS
   
   # Create database and user
   sudo -u postgres psql
   

   CREATE DATABASE rexec;
   CREATE USER rexec WITH PASSWORD 'your_secure_password';
   GRANT ALL PRIVILEGES ON DATABASE rexec TO rexec;
   \q
   
2. Start Redis

   # Linux
   sudo systemctl start redis
   
   # macOS
   brew services start redis
   
   # Verify Redis is running
   redis-cli ping
   # Should return: PONG
   

Build Rexec

1. Clone Repository

   git clone https://github.com/brimblehq/rexec.git
   cd rexec
   
2. Setup Development Environment

   Run the setup script to install dependencies and create required directories:

   make setup
   

   This command:

   • Downloads Go dependencies
   • Pulls base Docker images (ubuntu, debian, arch)
   • Creates /var/lib/rexec/volumes directory
   • Copies .env.example to .env
3. Build Frontend

   Build the Svelte web UI:

   make ui
   

   Or manually:

   cd frontend
   npm install
   npm run build
   cd ..
   

   The built frontend will be in the web/ directory.

4. Build Backend

   Compile the Go binary:

   make build
   

   This creates bin/rexec with the main server binary.

   To build everything (frontend + backend + CLI tools):

   make build-all
   
5. Build CLI Tools (Optional)

   Build the CLI, TUI, and agent binaries:

   make cli-all
   

   This creates:

   • bin/rexec-cli - Command-line interface
   • bin/rexec-tui - Terminal UI dashboard
   • bin/rexec-agent - Agent for connecting remote machines
   • bin/rexec-ssh - SSH gateway

Configuration

1. Create Environment File

   The setup script created .env from .env.example. Edit it:

   nano .env
   

   Minimum required configuration:

   .env

   # Server
   PORT=8080
   GIN_MODE=release
   BASE_URL=http://localhost:8080
   REXEC_APP_URL=http://localhost:8080
   REXEC_WS_HOST=localhost:8080
   
   # Security
   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
   REXEC_ENCRYPTION_KEY=your-32-character-encryption-key
   
   # Database
   DATABASE_URL=postgres://rexec:your_secure_password@localhost:5432/rexec?sslmode=disable
   
   # Redis
   REDIS_URL=redis://localhost:6379
   
   # Docker
   DOCKER_HOST=unix:///var/run/docker.sock
   VOLUME_PATH=/var/lib/rexec/volumes
   CONTAINER_NETWORK=rexec-network
   
   # Storage
   RECORDINGS_PATH=./data/recordings
   SCRIPTS_DIR=./scripts
   DOWNLOADS_DIR=./downloads
   
2. Generate Secure Keys

   Production Security: Generate secure random keys for production:

   # JWT Secret (any length)
   openssl rand -base64 32
   
   # Encryption Key (must be exactly 16, 24, or 32 bytes)
   openssl rand -base64 32 | cut -c1-32
   
3. Create Required Directories

   mkdir -p data/recordings
   mkdir -p downloads
   sudo mkdir -p /var/lib/rexec/volumes
   sudo chown -R $USER:$USER /var/lib/rexec
   

Running Rexec

1. Start the Server

   Using Make:

   make run
   

   Or directly:

   ./bin/rexec server
   

   The server will start on port 8080 (or your configured PORT).

2. Verify Server is Running

   Check the health endpoint:

   curl http://localhost:8080/health
   

   You should see a JSON response:

   {"status": "ok"}
   
3. Access Web Interface

   Open your browser to:

   http://localhost:8080
   

   Default credentials:

   • Username: admin
   • Password: admin

Development Mode

For development with hot-reloading:

1. Install Air (Hot Reload)

   go install github.com/air-verse/air@latest
   
2. Run Backend in Dev Mode

   make dev
   

   This watches for Go file changes and automatically rebuilds.

3. Run Frontend in Dev Mode

   In a separate terminal:

   make ui-dev
   

   Or manually:

   cd frontend
   npm run dev
   

   The Vite dev server will start on port 5173.

Building for Distribution

To build binaries for multiple platforms:

# Build agent for all platforms (linux/darwin amd64/arm64)
make agent-all

# Build CLI for all platforms
make cli-all-platforms

# Build TUI for all platforms
make tui-all-platforms

# Build SSH gateway for all platforms
make ssh-gateway-all

# Build everything for distribution
make dist

Binaries will be in the downloads/ directory:

downloads/
├── rexec-agent-linux-amd64
├── rexec-agent-linux-arm64
├── rexec-agent-darwin-amd64
├── rexec-agent-darwin-arm64
├── rexec-cli-linux-amd64
├── rexec-cli-darwin-arm64
└── ...

Docker Image Build

To build the Docker image manually:

make docker-build

Or using Docker directly:

docker build -t rexec:latest .

Running as a System Service

Systemd Service (Linux)

Create /etc/systemd/system/rexec.service:

[Unit]
Description=Rexec - Terminal as a Service
After=network.target postgresql.service redis.service docker.service

[Service]
Type=simple
User=rexec
WorkingDirectory=/opt/rexec
EnvironmentFile=/opt/rexec/.env
ExecStart=/opt/rexec/bin/rexec server
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable rexec
sudo systemctl start rexec
sudo systemctl status rexec

Makefile Commands

The Makefile provides many helpful commands:

make help          # Show all available commands
make build         # Build the Go server binary
make build-all     # Build UI + server + CLI tools
make run           # Build and run the application
make dev           # Run with hot reload
make test          # Run tests
make test-coverage # Run tests with coverage report
make lint          # Lint the code
make fmt           # Format the code
make clean         # Clean build artifacts
make deps          # Download Go dependencies

Troubleshooting

Docker Socket Permission Denied

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Port Already in Use

Change the PORT variable in .env or stop the conflicting service:

# Find process using port 8080
sudo lsof -i :8080

Database Connection Failed

Verify PostgreSQL is running and credentials are correct:

psql -U rexec -d rexec -h localhost

Frontend Build Fails

Clear npm cache and reinstall:

cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

Next Steps

Configuration

Learn about all environment variables and advanced configuration

Docker Compose

Deploy using Docker Compose for easier management