Kör dina egna Helium-tjänster

Det här sätter du upp

Helium är en integritetsfokuserad webbläsare byggd på Chromium. En del av dess funktioner går via Helium-tjänsterna, en uppsättning små webbtjänster:

nedladdningar av tillägg från Chrome Web Store, via en proxy, så att Google inte ser din adress;
filterlistorna till Heliums inbyggda uBlock Origin;
ordlistor för stavningskontroll;
listan med sökgenvägar, som !w för Wikipedia;
uppdateringar av några av webbläsarens inbyggda komponenter.

Som standard kommer de från Heliums egen server. Här körs de på din, så att de förfrågningarna går till en server du styr över, och tjänsterna hämtar det de behöver från internet med din servers adress.

Koden är imputs egen, från github.com/imputnet/helium-services, byggd oförändrad. Den är skriven för att köras på en egen server, med Docker. Här körs den i rootless Podman under en egen användare som heter helium, bakom Caddy från Podman-guiden, så att den kan dela server med dina andra appar. Fyra containrar deltar:

nginx skickar varje förfrågan till rätt tjänst, och serverar själv ordlistorna och sökgenvägarna;
ubo_proxy serverar filterlistorna;
ext_proxy och en reserv, ext_proxy_backup, hanterar tillägg.

Varje steg nedan har körts på en server hos Melonslab med Debian 13:

Helium 0.18 på Linux, inställd på att använda servern, hämtade sina filterlistor och sökgenvägar från den.
Ett tillägg laddades ner från Chrome Web Store via proxyn.
Varje tjänst svarade på samma sätt som Heliums egen server, även efter en omstart av servern och efter en uppdatering.

Tillsammans använde de fyra containrarna omkring 145 MB minne.

Innan du börjar

Du behöver:

en server uppsatt som i Podman-guiden, med Caddy igång;
en A-post och en AAAA-post för services.example.com som pekar på din server;
Helium på dina datorer, från helium.computer.

Exemplen använder services.example.com. Byt ut det mot ditt eget namn genomgående.

1. Skapa användaren

Som root installerar du Git, som hämtar koden, och skapar användaren:

apt install -y git
useradd -m -s /bin/bash helium
loginctl enable-linger helium
machinectl shell helium@

Allt härifrån till steg 5 körs som helium.

2. Ladda ner koden

git clone https://github.com/imputnet/helium-services ~/helium-services
mkdir -p ~/.config/containers

Koden anger en del avbilder utan att säga vilket register de kommer från, som nginx:1.30.1, vilket Debians Podman vägrar. Skapa ~/.config/containers/registries.conf, som säger åt den här användarens Podman att leta efter dem på Docker Hub:

# The helium-services Dockerfiles name images like nginx:... without a registry.
unqualified-search-registries = ["docker.io"]

3. Skapa certifikatet och hemligheten

imputs nginx tar bara emot HTTPS. Caddy pratar med den på serverns loopback-adress och behöver ett certifikat för det, som du skapar själv. Besökare ser aldrig det här certifikatet: Caddy visar dem sitt eget, från Let's Encrypt.

mkdir -p ~/helium-certs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -days 3650 \
  -subj "/CN=services.example.com" \
  -keyout ~/helium-certs/private.key -out ~/helium-certs/fullchain.pem

Tilläggsproxyn signerar nedladdningsadresserna den delar ut, så att ingen kan använda din server för att hämta något annat. Skapa dess hemlighet:

openssl rand -hex 32 | tr -d '\n' | podman secret create helium-hmac-secret -

4. Definiera containrarna

mkdir -p ~/.config/containers/systemd
cd ~/.config/containers/systemd

nginx hittar varje tjänst på dess containernamn, och slår upp namnen en gång, när den startar. Tjänsterna får därför fasta adresser på ett eget nätverk, så att nginx fortfarande når en tjänst efter att den startats om.

Skapa helium.network:

[Network]
NetworkName=helium
# Fixed addresses: nginx looks the services up once, when it starts.
Subnet=10.90.0.0/24

Skapa helium-ubo_proxy.container:

[Container]
ContainerName=ubo_proxy
Image=localhost/helium-ubo
Network=helium.network
IP=10.90.0.11
ReadOnly=true
Environment=UBO_PROXY_BASE_URL=https://services.example.com/ubo/
Environment=UBO_USE_ORIGINAL_UBLOCK_ASSETS=0

[Service]
Restart=always

[Install]
WantedBy=default.target

Behåll / i slutet av UBO_PROXY_BASE_URL, som i imputs exempelfil. Utan det saknar filterlistornas adresser /ubo/, och varje lista misslyckas med att laddas ner.

Skapa helium-ext_proxy.container:

[Container]
ContainerName=ext_proxy
Image=localhost/helium-ext
Network=helium.network
IP=10.90.0.12
ReadOnly=true
Secret=helium-hmac-secret,type=env,target=HMAC_SECRET
Environment=PROXY_BASE_URL=https://services.example.com/ext

[Service]
Restart=always

[Install]
WantedBy=default.target

Kopiera den till helium-ext_proxy_backup.container, och ändra i kopian ContainerName till ext_proxy_backup och IP till 10.90.0.13:

sed -e 's/^ContainerName=ext_proxy$/ContainerName=ext_proxy_backup/' -e 's/^IP=10.90.0.12$/IP=10.90.0.13/' \
  helium-ext_proxy.container > helium-ext_proxy_backup.container

nginx skickar förfrågningar om tillägg till reserven när den första proxyn inte svarar, och nginx startar bara om båda finns.

Skapa helium-nginx.container:

[Unit]
Description=Helium services, behind Caddy
After=helium-ext_proxy.service helium-ext_proxy_backup.service helium-ubo_proxy.service
Wants=helium-ext_proxy.service helium-ext_proxy_backup.service helium-ubo_proxy.service

[Container]
ContainerName=helium_nginx
Image=localhost/helium-nginx
Network=helium.network
RunInit=true
ReadOnly=true
Tmpfs=/tmp:size=512m
ShmSize=512m
Volume=%h/helium-certs:/certs:ro
# Only Caddy, on this server, can reach it: the port is not open to the internet.
PublishPort=127.0.0.1:8090:443

[Service]
Restart=always

[Install]
WantedBy=default.target

Det är inställningarna från imputs egen compose.yml, utom porten.

5. Bygg och starta

Avbilderna byggs på din server från koden. Ett skript gör det första gången, och uppdaterar sedan koden och bygger om när den har ändrats. Skapa ~/bin/update-helium-services:

mkdir -p ~/bin ~/.config/systemd/user

#!/bin/sh
# Fetch helium-services, and rebuild and restart it when the code has changed.
set -e
cd ~/helium-services
old=$(git rev-parse HEAD)
git pull -q
if [ "$(git rev-parse HEAD)" = "$old" ] && podman image exists localhost/helium-nginx; then
    exit 0
fi
podman build -q -t localhost/helium-nginx --build-arg SERVICES_HOSTNAME=services.example.com -f nginx/Dockerfile svc
podman build -q -t localhost/helium-ubo svc/ubo
podman build -q -t localhost/helium-ext svc/extension-proxy
systemctl --user restart helium-ubo_proxy helium-ext_proxy helium-ext_proxy_backup helium-nginx
podman image prune -f

Namnet byggs in i nginx-avbilden, så det står i skriptet. Gör det körbart och kör det:

chmod +x ~/bin/update-helium-services
systemctl --user daemon-reload
~/bin/update-helium-services

Skriptet bygger tre avbilder, vilket tog under en halv minut på vår testserver, och startar de fyra containrarna. Varningar om att HEALTHCHECK is not supported är ofarliga.

För att köra skriptet en gång i veckan skapar du ~/.config/systemd/user/update-helium-services.service:

[Unit]
Description=Update helium-services

[Service]
Type=oneshot
ExecStart=%h/bin/update-helium-services

Och ~/.config/systemd/user/update-helium-services.timer:

[Unit]
Description=Update helium-services once a week

[Timer]
OnCalendar=weekly
RandomizedDelaySec=6h
Persistent=true

[Install]
WantedBy=timers.target

systemctl --user daemon-reload
systemctl --user enable --now update-helium-services.timer

När inget har ändrats tar en körning omkring en sekund och startar inte om något.

6. Sätt Caddy framför

Gå tillbaka till root med exit, byt till machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:

services.example.com {
    reverse_proxy https://127.0.0.1:8090 {
        header_up Host {host}
        transport http {
            tls_server_name services.example.com
            tls_insecure_skip_verify
        }
    }
}

nginx svarar bara på förfrågningar för sitt eget namn. tls_server_name och header_up Host skickar vidare det namnet: utan dem skulle Caddy använda 127.0.0.1:8090, och nginx skulle svara 404 på allt. tls_insecure_skip_verify godtar certifikatet från steg 3, som ingen utfärdare har signerat. Anslutningen lämnar aldrig servern, som för de andra apparna bakom Caddy.

Starta om Caddy med systemctl --user restart caddy, och kontrollera från valfri dator:

curl -s -o /dev/null -w '%{http_code}\n' https://services.example.com/bangs.json
curl -s --compressed https://services.example.com/ubo/assets.json | head -c 300

Det första kommandot skriver ut 200. Det andra visar adresser som börjar med https://services.example.com/ubo/. Ordlistorna, på https://services.example.com/dict/, dyker upp en eller två minuter efter varje start, när nginx har laddat ner dem.

7. Använd det i Helium

Slutför först Heliums installation, sidan den visar när den startar första gången, och tillåt Helium-tjänsterna där. Tills dess kontaktar Helium inga tjänster alls, och det står i dess inställningar.

Öppna sedan Settings, Privacy and security och Helium services. Ange https://services.example.com under Use your own instance of Helium services och tryck Enter. Från och med då hämtar Helium sina filterlistor från din server. Installera ett tillägg från Chrome Web Store för att kontrollera proxyn: nedladdningen går nu via din server.

Den som känner till adressen kan använda din server på samma sätt, som med Heliums egen.

Felsökning

Varje adress svarar 404. Caddy skickar inte vidare namnet. Kontrollera header_up Host {host} och tls_server_name i steg 6.

short-name ... did not resolve to an alias när du bygger. Filen från steg 2, ~/.config/containers/registries.conf, saknas.

Filterlistorna misslyckas, och deras adresser saknar /ubo/. UBO_PROXY_BASE_URL saknar sitt / i slutet. Lägg till det och kör sedan systemctl --user daemon-reload och systemctl --user restart helium-ubo_proxy som helium.

502 Bad Gateway. En tjänst körs inte. Kör som helium: systemctl --user status helium-nginx helium-ubo_proxy helium-ext_proxy helium-ext_proxy_backup visar vilken tjänst det gäller, och journalctl --user -u update-helium-services visar om den senaste uppdateringen misslyckades.

Kör dina egna Helium-tjänster

Mer i Utveckling och drift