Domains and reverse proxies
A Gib server listens on one plain HTTP port. To serve it on a real domain name with encryption, you need DNS records and, in most setups, a reverse proxy. This page shows both. It uses example.com names. Replace them with your own.
Host names an instance needs
Section titled “Host names an instance needs”| Name | Needed | What it serves |
|---|---|---|
images.example.com |
Yes | The application: the API, the images and the interface. |
docs.example.com |
No | The documentation site. |
The same server process answers for both names. It chooses by the Host header of each request. A request whose host name is listed in DOCS_HOSTNAMES gets the documentation site and nothing else. The API and the interface do not answer on that name. Every other host name gets the application, and the documentation site is not reachable there. DOCS_HOSTNAMES is a comma-separated list, and it is empty by default, which turns the documentation site off. You must build the site first with yarn workspace docs build. The server reads it from packages/docs/dist.
Because the server reads the Host header, your proxy must pass the original header on. Both example configurations below do.
DNS records
Section titled “DNS records”Create one record for each name at your DNS provider.
| Type | Name | Value |
|---|---|---|
A |
images |
The IPv4 address of your server. |
AAAA |
images |
The IPv6 address of your server, if it has one. |
CNAME |
docs |
images.example.com, or an A and AAAA record with the same addresses. |
Notes:
- A
CNAMEis allowed on a sub-domain such asimages. It is not allowed on the bare domainexample.com. UseAandAAAArecords there. - If a content delivery network or a proxy service sits in front of the server, set those records to the proxied mode that your provider offers. Then the provider answers the request and forwards it to your server. See A content delivery network or a tunnel in front.
- A
wwwname is optional. If you want one, point it at the same server and redirect it to the main name. The configurations below show how. - Open ports 80 and 443 on the server. Port 80 is needed for certificate issue and for the redirect to HTTPS.
Settings that must match the public address
Section titled “Settings that must match the public address”Two settings hold the public address of your instance. Set both to the address people really use, with the https:// prefix and no trailing slash.
| Setting | When it is read | What it controls |
|---|---|---|
ROOT_URI |
When the server starts. | The address inside every /image/direct/<hash> link that the server builds. These are the logoURI values in token lists. The default is http://localhost:3456. |
PUBLIC_BASE_URL |
When you build the interface. | The address the interface calls for the API. Empty means the same origin as the page. |
What breaks when they do not match:
- If
ROOT_URIis wrong, the lists still load, but eachlogoURIpoints at the wrong host. A browser or a wallet that follows the link fails to load the logo. With the default, every link points atlocalhost. - If
PUBLIC_BASE_URLis wrong, the interface calls an address that does not answer or that blocks it. Leave it empty when the interface and the API share one host name, as in this page. The setting is baked into the build, so you must build the interface again after you change it.
Change ROOT_URI in the server environment and restart the server. See Configuration for every setting.
What the server does behind a proxy
Section titled “What the server does behind a proxy”Read this before you write a proxy configuration. These facts come from the server code.
- Port. The server listens on
PORT, which is3000by default. - Client address. The server does not use the client address for anything. It does not set the Express
trust proxyoption, and its resize limits count per server process, not per client. So a proxy does not change how those limits work. It also means theX-Forwarded-Forheader is passed on but ignored. - Host. The server reads the host name from the
Hostheader. It does not readX-Forwarded-Host. The proxy must send the originalHostheader. - Request body. The server accepts JSON bodies up to 1 megabyte. An image submission is limited to 512 kilobytes of image data inside that body. Set the proxy limit to 1 megabyte or more.
- Compression. The server compresses responses itself. Do not compress again in the proxy.
- Cache headers. The server sets
Cache-Controlitself. Hashed build files under/assets/and/_astro/arepublic, max-age=31536000, immutable.index.html,sw.jsand the documentation HTML pages areno-cache. Images usemax-agefromCACHE_SECONDS, and/image/direct/<hash>is immutable. See Caching. Do not override these headers in the proxy. - Slow requests. A first request for a new image size resizes the image in the server. A fetch from a slow provider can also take time. Set the proxy read timeout to 60 seconds, not the short default of some proxies.
- WebSocket. The server does not use WebSocket, so the proxy needs no upgrade handling.
- Health.
GET /healthanswers on every host name. It answers 200 with{"status":"ok"}when the server is ready, and 503 while it starts.
Caddy gets and renews certificates from Let’s Encrypt by itself. It passes the original Host header and sets X-Forwarded-For and X-Forwarded-Proto by default. Put this in /etc/caddy/Caddyfile:
# Optional: send www to the main name.www.images.example.com { redir https://images.example.com{uri} permanent}
# The application and, with DOCS_HOSTNAMES set, the documentation site.images.example.com, docs.example.com { # Gib compresses its own responses, so no `encode` directive here.
# Allow image submissions, which are JSON up to 1 MB. request_body { max_size 1MB }
reverse_proxy 127.0.0.1:3000 { # Caddy sends the original Host header by default. # Wait for slow resizes and slow provider fetches. transport http { response_header_timeout 60s } health_uri /health health_interval 30s }}Caddy does not touch Cache-Control from the upstream, so the server headers reach the client unchanged. Check the file, then reload:
caddy validate --config /etc/caddy/Caddyfilesudo systemctl reload caddyIf the proxy runs in a container on the same Docker network as the server, replace 127.0.0.1:3000 with the service name, for example server:3000.
Install nginx and certbot, point DNS at the server, then get a certificate for each name:
sudo certbot certonly --nginx -d images.example.com -d docs.example.com -d www.images.example.comCertbot renews the certificates by itself. Put this in /etc/nginx/conf.d/gib.conf:
# Send plain HTTP to HTTPS.server { listen 80; listen [::]:80; server_name images.example.com docs.example.com www.images.example.com; return 301 https://$host$request_uri;}
# Optional: send www to the main name.server { listen 443 ssl; listen [::]:443 ssl; http2 on; server_name www.images.example.com;
ssl_certificate /etc/letsencrypt/live/images.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/images.example.com/privkey.pem;
return 301 https://images.example.com$request_uri;}
# The application and, with DOCS_HOSTNAMES set, the documentation site.server { listen 443 ssl; listen [::]:443 ssl; http2 on; server_name images.example.com docs.example.com;
ssl_certificate /etc/letsencrypt/live/images.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/images.example.com/privkey.pem;
# Image submissions are JSON up to 1 MB. client_max_body_size 1m;
# Gib compresses its own responses. Leave nginx compression off. gzip off;
location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1;
# The server chooses the application or the documentation site # from this header, so it must be the original host name. 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;
# Wait for slow resizes and slow provider fetches. proxy_connect_timeout 5s; proxy_read_timeout 60s; proxy_send_timeout 60s;
# Do not override the server's Cache-Control headers. nginx passes # them on by default. Do not add expires or add_header Cache-Control. }}Test the file, then reload:
sudo nginx -tsudo systemctl reload nginxIf the server runs in a container on the same Docker network, replace 127.0.0.1:3000 with the service name, for example server:3000.
A content delivery network or a tunnel in front
Section titled “A content delivery network or a tunnel in front”You can put a content delivery network, such as the Cloudflare proxy, in front of the server. You can also use a tunnel product, such as Cloudflare Tunnel, which connects out from your server so that you open no inbound port. The rules are the same for all of them:
- The original host name must reach the server in the
Hostheader. If the product rewrites the host to an internal name, the documentation site never answers and the application answers on every name. In a tunnel, set the host header or the origin server name to the public name. - Let the product respect the origin cache headers. Do not set a rule that replaces the
Cache-Controlof the server. A rule that caches/and/index.htmlfor a short time, such as 60 seconds, is fine and makes the page fast for first-time visitors. - Tell Gib where to read the real address of the caller. Behind a proxy or a tunnel, every connection comes from the proxy, so Gib cannot tell callers apart and keeps only its whole-service limit on plated images. Set
CLIENT_ADDRESS_HEADERto the header that your product fills with the caller’s address (Cloudflare usescf-connecting-ip), and each caller gets its own limit. Set it only when the server can be reached through the proxy alone: a caller that reaches the server directly could write that header itself and take a fresh limit with every request. Gib never trusts a header that you have not named. - Caching 404 answers for a short time is optional. Providers that have no image for a token cause many repeated requests for the same missing image. A short cache, for example one hour, spares your server. The server sends its own lifetime with a 404. A product that follows the origin lifetimes may keep it for less than you want, so set a rule for it if you need a longer time.
- After a deploy, a cached copy made before it can answer a plain request. Add a random query parameter when you test.
If you terminate encryption at the content delivery network, you can keep the proxy to the server on plain HTTP. Then X-Forwarded-Proto tells you the original protocol.
Check that it works
Section titled “Check that it works”Run these from any machine. Replace the names with yours.
# The application answers, over HTTPS, with its own cache headers.curl -I https://images.example.com/healthcurl -s https://images.example.com/health# {"status":"ok"}
# An image carries provenance headers and a lifetime.curl -I "https://images.example.com/image/1/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599?cachecheck=$RANDOM"# Look for: cache-control, link, x-license
# The documentation host answers with the site, not the API.curl -I https://docs.example.com/# Expect: 200 and cache-control: no-cachecurl -I https://docs.example.com/list# Expect: 404, because the API does not answer on the documentation host
# Plain HTTP redirects to HTTPS, and www redirects to the main name.curl -I http://images.example.com/curl -I https://www.images.example.com/Then check these points:
- The
linkandx-licenseheaders are present on every image response. The server sets them always, so if they are missing, the answer did not come from your server. Suspect a cache in front first. cache-controlis the value from the server and not a value your proxy invented.- A token list has
logoURIvalues that start with your public address. If they start withhttp://localhost:3456, setROOT_URIand restart. - The interface loads at
https://images.example.com/and calls the same host. - The
Hostcheck:https://docs.example.com/returns the documentation site, andhttps://images.example.com/returns the interface.