G

gitlab-pages

GitLab Pages daemon used to serve static websites for GitLab users

Name Last Update
Godeps Loading commit data...
internal/httputil Loading commit data...
metrics Loading commit data...
shared/pages Loading commit data...
vendor Loading commit data...
.gitignore Loading commit data...
.gitlab-ci.yml Loading commit data...
404.go Loading commit data...
CHANGELOG Loading commit data...
LICENSE Loading commit data...
Makefile Loading commit data...
README.md Loading commit data...
VERSION Loading commit data...
acceptance_test.go Loading commit data...
app.go Loading commit data...
app_config.go Loading commit data...
daemon.go Loading commit data...
domain.go Loading commit data...
domain_config.go Loading commit data...
domain_config_test.go Loading commit data...
domain_test.go Loading commit data...
domains.go Loading commit data...
domains_test.go Loading commit data...
helpers.go Loading commit data...
helpers_test.go Loading commit data...
logging.go Loading commit data...
logging_test.go Loading commit data...
main.go Loading commit data...
multi_string_flag.go Loading commit data...
multi_string_flag_test.go Loading commit data...
server.go Loading commit data...

GitLab Pages Daemon

build status

coverage report

This is simple HTTP server written in Go made to serve GitLab Pages with CNAMEs and SNI using HTTP/HTTP2.

This is made to work in small-to-medium scale environments. In large environment it can be time consuming to list all directories, and CNAMEs.

How it generates routes

  1. It reads the pages-root directory to list all groups
  2. It looks for config.json file in pages-root/group/project directory, reads them and creates mapping for custom domains and certificates.
  3. It generates virtual-host from these data.
  4. Periodically (every second) it checks the pages-root/.update file and reads its content to verify if there was update.

To force route refresh, reload of configs fill the pages-root/.update with random content. The reload will be done asynchronously, and it will not interrupt the current requests.

How it serves content

  1. When client initiates the TLS connection, the GitLab-Pages daemon looks in hash map for virtual hosts and tries to use loaded from config.json certificate.

  2. When client asks HTTP server the GitLab-Pages daemon looks in hash map for registered virtual hosts.

  3. The URL.Path is split into /<project>/<subpath> and we daemon tries to load: pages-root/group/project/public/subpath.

  4. If file was not found it will try to load pages-root/group/<host>/public/<URL.Path>.

  5. If requested path is directory, the index.html will be served.

How it should be run?

Ideally the GitLab Pages should run without load balancer.

If load balancer is required, the HTTP can be served in HTTP mode. For HTTPS traffic load balancer should be run in TCP-mode. If load balancer is run in SSL-offloading mode the custom TLS certificate will not work.

How to run it

Example:

CGO_ENABLED=0 GO15VENDOREXPERIMENT=1 go build
./gitlab-pages -listen-https "" -listen-http ":8090" -pages-root path/to/gitlab/shared/pages -pages-domain example.com

Run daemon in secure mode

When compiled with CGO_ENABLED=0 (which is the default), gitlab-pages is a static binary and so can be run in chroot with dropped privileges.

To enter this mode, run gitlab-pages as the root user and pass it the -daemon-uid and -daemon-gid arguments to specify the user you want it to run as.

The daemon start listening on ports as root, reads certificates as root and re-executes itself as specified user. When re-executing it copies it's own binary to pages-root and changes root to that directory.

This make it possible to listen on privileged ports and makes it harded the process to read files outside of pages-root.

Example:

go build
sudo ./gitlab-pages -listen-http ":80" -pages-root path/to/gitlab/shared/pages -pages-domain example.com -daemon-uid 1000 -daemon-gid 1000

Listen on multiple ports

Each of the listen-http, listen-https and listen-proxy arguments can be provided multiple times. Gitlab Pages will accept connections to them all.

Example:

go build
./gitlab-pages -listen-http "10.0.0.1:8080" -listen-https "[fd00::1]:8080" -pages-root path/to/gitlab/shared/pages -pages-domain example.com

This is most useful in dual-stack environments (IPv4+IPv6) where both Gitlab Pages and another HTTP server have to co-exist on the same server.

Enable Prometheus Metrics

For monitoring purposes, one could pass the -metrics-address flag when starting. This will expose general metrics about the Go runtime and pages application for Prometheus to scrape.

Example:

./gitlab-pages -listen-http ":8090" -metrics-address ":9235" -pages-root path/to/gitlab/shared/pages -pages-domain example.com

License

MIT