diff options
author | Nick Thomas <nick@gitlab.com> | 2017-08-24 17:54:32 +0300 |
---|---|---|
committer | Nick Thomas <nick@gitlab.com> | 2017-09-14 00:29:25 +0300 |
commit | a9807c3c43ad4b42843a7593c7532b45cf26d917 (patch) | |
tree | 08cce2550a5d3c7a58d4233053593912a965bfd8 /README.md | |
parent | f82e9dab29ddf771d8d10cf8cb4d7b7ac4b1ba29 (diff) |
Cleanup the README file
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 71 |
1 files changed, 44 insertions, 27 deletions
@@ -4,41 +4,54 @@ [![coverage report](https://gitlab.com/gitlab-org/gitlab-pages/badges/master/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-pages/commits/master) -This is simple HTTP server written in Go made to serve GitLab Pages with CNAMEs and SNI using HTTP/HTTP2. -The minimum supported Go version is 1.8. +This is a simple HTTP server written in Go, made to serve GitLab Pages with +CNAMEs and SNI using HTTP/HTTP2. The minimum supported Go version is 1.8. -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. +This is made to work in small to medium-scale environments. Start-up time scales +with the number of projects being served, so the daemon is currently unsuitable +for very large-scale environments. ### 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. +1. It reads the `pages-root` directory to list all groups. +2. It looks for `config.json` files in `pages-root/group/project` directories, + reads them and creates mapping for custom domains and certificates. +3. It generates virtual hosts from these data. +4. Periodically (every second) it checks the `pages-root/.update` file and reads + its content to verify if there was an 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. +To reload the configuration, fill the `pages-root/.update` file 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. +1. When client initiates the TLS connection, the GitLab-Pages daemon looks in + the generated configuration for virtual hosts. If present, it uses the TLS + key and certificate in `config.json`, otherwise it falls back to the global + configuration. -2. When client asks HTTP server the GitLab-Pages daemon looks in hash map for registered virtual hosts. +2. When client connects to a HTTP port the GitLab-Pages daemon looks in the + generated configuration for a matching virtual host. -3. The URL.Path is split into `/<project>/<subpath>` and we daemon tries to load: `pages-root/group/project/public/subpath`. +3. The URL.Path is split into `/<project>/<subpath>` and the 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>`. +4. If the file is 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. +5. If requested path is a directory, the `index.html` will be served. + +6. If `.../path.gz` exists, it will be served instead of the main file, with + a `Content-Encoding: gzip` header. This allows compressed versions of the + files to be precalculated, saving CPU time and network bandwidth. ### How it should be run? -Ideally the GitLab Pages should run without load balancer. +Ideally the GitLab Pages should run without any load balancer in front of it. -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. +If a load balancer is required, the HTTP can be served in HTTP mode. For HTTPS +traffic, the load balancer should be run in TCP mode. If the load balancer is +run in SSL-offloading mode, custom TLS certificates will not work. ### How to run it @@ -57,10 +70,12 @@ 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. +The daemon starts listening on ports and reads certificates as root, then +re-executes itself as the specified user. When re-executing it copies its 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`. +This make it possible to listen on privileged ports and makes it harder for the +process to read files outside of `pages-root`. Example: ``` @@ -70,7 +85,8 @@ $ sudo ./gitlab-pages -listen-http ":80" -pages-root path/to/gitlab/shared/pages ### 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. +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: ``` @@ -78,13 +94,14 @@ $ make $ ./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. +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](https://prometheus.io/) to scrape. +For monitoring purposes, you can pass the `-metrics-address` flag when starting. +This will expose general metrics about the Go runtime and pages application for +[Prometheus](https://prometheus.io/) to scrape. Example: ``` |