Before you install: server, DNS and names

The server

• System. Debian or Ubuntu, with apt. The installer refuses other systems with "This installer supports Debian and Ubuntu (apt); this system is …". The admin service needs Python 3.9 or later, so use Debian 11 or later, or Ubuntu 22.04 or later.
• systemd. It must be running: the services are systemd units. (--no-systemd exists only for testing.)
• nginx. The installer installs the distribution's package when nginx is missing, and works with an nginx configured from /etc/nginx/nginx.conf. Without that file it stops: "There is no /etc/nginx/nginx.conf: this installer works with the nginx package of Debian and Ubuntu."
• Root. You run the installer with sudo.
• Packages. The installer adds only what is missing: nginx, certbot, python3, python3-pil (Pillow), python3-pycryptodome (only when the system has no keccak-256 otherwise), openssl and curl.

What COLLAB itself needs is small. nginx serves static files, the admin service is one Python process listening on 127.0.0.1, and the prerender job runs every 10 minutes at low priority (nice 10, idle I/O). On disk, a copy of release 2.2.0 takes about 20 MB, and the installer keeps three: the current release and the two before it. The prerender job's pages and images grow with the number of DAOs and tokens. The Status tab warns when less than a tenth of the disk is free.

Ports

No other program may hold ports 80 or 443. The installer checks with ss and stops before it changes anything:

Port 80 is used by another program:
  …
Stop it, then run this again. Nothing was changed.

Apache or Caddy on the same server are the usual cause. On a server without nginx, the same check runs before nginx's package is installed. If port 8411 is taken on 127.0.0.1, pick another one with --admin-port N.

DNS: point every name first

Create the records before you install. The certificate covers only the names whose DNS points at the server when the installer runs; a name that does not is left out, with a warning, and gets its certificate on a later run.

Add an AAAA record only when the server has a working public IPv6 address: browsers and Let's Encrypt use it when it is there.

Checking with dig

From your computer:

for n in collab.genesisl1.com dao.genesisl1.com collab.descifi.org dao.descifi.org; do
  echo "$n: $(dig +short A "$n" | tr '\n' ' ')$(dig +short AAAA "$n" | tr '\n' ' ')"
done

On the server, ip -o addr show scope global lists its own addresses, and getent ahosts collab.genesisl1.com shows what the server itself resolves for a name, which is what the installer looks at.

How the installer decides

For each name, the installer looks up its addresses:

• the name passes when one of them is an address of this server;
• behind NAT or a proxy, where the address is not on the server itself, it passes when a request for a one-time token through the name, over HTTP, reaches this server. The server sends that request itself, so behind NAT the router must send it back in (NAT loopback, or hairpinning);
• otherwise it reports why: "no DNS record (or it does not resolve from here)" or "points at …, not at this server".

When the main name does not pass, there is no certificate at all, and port 80 answers with a short "being set up" notice until there is one.

Cloudflare

If the names are on Cloudflare, set them to DNS only (the grey cloud), at least until the certificate is issued. Domains, redirects and certificates says what to set if you turn the proxy on afterwards.

The firewall

• ufw. When ufw is active, the installer allows 80/tcp and 443/tcp itself and says so: "ufw: ports 80 and 443 are open".
• Other firewalls. nftables or iptables rules, and a cloud provider's firewall or security group, are yours to open for TCP 80 and 443. Let's Encrypt must reach port 80 from the internet, for the first certificate and for every renewal.
• Keep closed. Port 8411 serves only 127.0.0.1; never forward it.
• Outbound. The server needs outbound HTTPS to the RPC endpoints and to api.coingecko.com for the prerender job, and to Let's Encrypt for certbot. apt needs the package mirrors, often over plain HTTP.

An nginx that already serves other sites

COLLAB can share an nginx with other sites. The installer adds one file of its own and changes nothing else:

• /etc/nginx/sites-available/collab.conf, linked as sites-enabled/zz-collab.conf, so it loads after the other sites (or conf.d/zz-collab.conf when nginx.conf includes no sites-enabled);
• it never edits the default site or another site's file, and it marks no server as default_server.

It checks nginx before it changes anything, and stops without changing anything when:

• nginx's configuration does not pass its own test (nginx -T) now;

• another site answers for one of COLLAB's names exactly:

  Another site on this nginx answers for a name COLLAB would take:
    dao.genesisl1.com  (/etc/nginx/sites-enabled/example.conf)
  Remove the name there, or leave it out here (--main, --alias, --no-aliases). Nothing was changed.

• a file at COLLAB's path exists that the installer did not write ("… exists and was not written by this installer: move it away (or remove it), then run this again.").

A wildcard or regular-expression name of another site that also covers a COLLAB name (such as *.genesisl1.com) is reported but not refused: nginx prefers an exact name, so that name comes to COLLAB.

Two settings of the listening sockets are shared by every site on a port, so the installer adapts to the other sites rather than change them:

• HTTP/2. From nginx 1.25.1 it is set per site (http2 on;). Before that, COLLAB uses HTTP/2 on port 443 only when the other sites there already do; otherwise it says "HTTP/2 stays off".
• IPv6. COLLAB listens on [::] only when the server has IPv6 and the other sites on that port, if there are any, listen on it too.
• Addresses. When another site listens on one of the server's own addresses on a port, rather than on all of them, COLLAB listens on that address too: nginx gives a request to the sites of the most specific address first.

Which site answers a request for a name nobody configured, or for the server's bare IP address, is described in Domains, redirects and certificates.

Choosing the main host

One name is the site; the others answer 301 to the same path and query on it. Visitors' settings and wallet connections belong to one origin, so a single main host keeps them in one place.

On a first install, --main dao.genesisl1.com alone makes the other three of the four names its aliases. The installer remembers the main host and the aliases; later runs keep them unless you name them again. Changing the main host after the install is explained in Domains, redirects and certificates.

The RPC endpoint of the prerender job

--rpc URL names the GenesisL1 JSON-RPC endpoint the prerender job reads, for example a node of your own. Without it, the job tries the site's own endpoints in order and uses the first that answers for chain 29: those of the site settings, else the GenesisL1 RPC (https://rpc.genesisl1.org) and the GL1X JSON-RPC (https://gl1x.com/api/eth-rpc). --rpc "" goes back to them.

The URL must be https, or http only for localhost and 127.0.0.1, with a plain host name. The installer refuses anything else: "--rpc takes the https URL of a GenesisL1 JSON-RPC endpoint". This option changes only the prerender job; visitors read the chain through the endpoints in Site settings.

What to have ready

• SSH access with sudo, and the release archive with its .sha256 file.
• An email address for the Let's Encrypt account (--email). It is optional.
• A browser wallet with L1 on GenesisL1 for the deployment: MetaMask, Rabby, or Keplr in EVM mode. The 20 creations used 42,953,788 gas in the release rehearsal, about 2.15 L1 at a 50 gwei gas price; the Deploy tab shows the exact estimate at the current price before you start. See Deploy the protocol from /admin.
• Optional. A Google Analytics 4 measurement ID, and the links of your website and accounts, for the site settings.

Related

• Installing COLLAB on a server
• Domains, redirects and certificates
• Running a COLLAB site
• Troubleshooting