How to Install IF1-0 on Your Own Server

IF1-0 (Internet Fix 1.0) is a Quarkus-based proxy server with a built-in web UI for internet search. It supports domain whitelisting/blacklisting and integrates optional with an LLM embedding endpoint to offer a semantic search feature. This guide walks you through a full production setup on a Debian server using Docker and nginx.

Architecture Overview

Client Browser
     │
     │  HTTPS/443
     ▼
  nginx (TLS termination via Let's Encrypt)
     │
     │  HTTP/9080 (internal)
     ▼
  Quarkus App (Docker)
     │
     ├── Web UI          → port 9080
     └── Proxy Socket    → port 8080

• Port 9080 — Web client for member registration and internet search (exposed via nginx with HTTPS)
• Port 8080 — HTTP proxy socket (used as browser proxy endpoint)

Prerequisites

• Debian GNU/Linux 13 (trixie) server with root access
• A domain name pointing to your server (e.g. proxy.example.org)
• Java 21, Maven, Docker, nginx, and certbot installed (see below)

1. Initial Server Setup

Create a non-root user

useradd -m proxy -s /bin/bash
passwd proxy
/usr/sbin/usermod -aG sudo proxy

Update the system

apt update && apt upgrade -y

Install Docker

apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
tee /etc/apt/sources.list.d/docker.list > /dev/null

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Install nginx, certbot, Java 21, and Git

apt install -y nginx certbot python3-certbot-nginx
apt install -y openjdk-21-jdk-headless maven
apt install -y git

2. Clone the IF1-0 Repository

git clone https://codeberg.org/if1-0/if-1.0-quarkus-implementation.git
cd if-1.0-quarkus-implementation

3. Configure the Environment

Before building, create a .env file in the project root. This file defines the Cassandra database connection, the LLM embedding endpoint, and optionally trusted peer proxies.

cat > .env << 'EOF'
CASSANDRA_CONTACTPOINTS=cassandra
CASSANDRA_KEYSPACE=if10
EMBEDDING_API_ENDPOINT=https://embeddings.your-llm-server.com/
EMBEDDING_API_KEY=your-api-key-here
EOF

Note: Never commit .env to version control. It contains sensitive credentials.
The LLM endpoint is optional and only needed if you like to publish a web ui.

4. Generate RSA Keys

IF1-0 uses RSA keys for JWT signing. Generate them into the resources directory:

openssl genrsa -out src/main/resources/privateKey.pem 2048
openssl rsa -in src/main/resources/privateKey.pem -pubout \
    -out src/main/resources/publicKey.pem

5. Build and Run with Docker

The project ships with a devi helper script that wraps Maven and Docker commands. Here is a quick reference:

First-time build and start

./devi -docker       # builds the Docker image
./devi -start-prod   # starts all containers in the background

Verify the containers are running

docker compose logs -f

6. Configure nginx

Create a new nginx site config for your domain:

nano /etc/nginx/sites-available/proxy.example.org

server {
    listen 80;
    server_name proxy.example.org;

    location / {
        proxy_pass http://localhost:9080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site and test the config:

ln -s /etc/nginx/sites-available/proxy.example.org /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

7. Enable HTTPS with Let's Encrypt

certbot will automatically update your nginx config to add TLS:

certbot --nginx -d proxy.example.org

After this, your web UI is available at https://proxy.example.org with a valid certificate. certbot also sets up automatic renewal.

8. Configure the Browser Proxy

To route browser traffic through IF1-0, configure your browser's HTTP proxy settings:

Proxy host: proxy.example.org
Port:       8080

Only domains on the configured whitelist will be allowed through. All other requests will be blocked by IF1-0.

Note: Port 8080 uses plain HTTP between the browser and the proxy server. The connections to the actual target websites remain encrypted via HTTPS as usual. This is standard behavior for explicit HTTP proxies.

Useful Commands

# Follow live logs
docker compose logs -f

# Stop all containers
./devi -stop-prod

# Open Cassandra shell
./devi -cassandra

# Rebuild after code changes
./devi -docker && ./devi -start-prod