kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/development/pages/index.md

7.1 KiB
Raw Blame History

type stage group info description
reference, dev Create Editor To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments GitLab's development guidelines for GitLab Pages

Getting started with development

Configuring GitLab Pages hostname

GitLab Pages needs a hostname or domain, as each different GitLab Pages site is accessed via a subdomain. GitLab Pages hostname can be set in different manners:

Without wildcard, editing your hosts file

As /etc/hosts don't support wildcard hostnames, you must configure one entry for GitLab Pages, and then one entry for each page site:

127.0.0.1 gdk.test           # If you're using GDK
127.0.0.1 pages.gdk.test     # Pages host
# Any namespace/group/user needs to be added
# as a subdomain to the pages host. This is because
# /etc/hosts doesn't accept wildcards
127.0.0.1 root.pages.gdk.test # for the root pages

With DNS wildcard alternatives

If instead of editing your /etc/hosts you'd prefer to use a DNS wildcard, you can use:

Configuring GitLab Pages without GDK

Create a gitlab-pages.conf in the root of the GitLab Pages site, like:

# Default port is 3010, but you can use any other
listen-http=:3010

# Your local GitLab Pages domain
pages-domain=pages.gdk.test

# Directory where the pages are stored
pages-root=shared/pages

# Show more information in the logs
log-verbose=true

To see more options you can check internal/config/flags.go or run gitlab-pages --help.

Running GitLab Pages manually

For any changes in the code, you must run make to build the app. It's best to just always run it before you start the app. It's quick to build so don't worry!

make && ./gitlab-pages -config=gitlab-pages.conf

Configuring GitLab Pages with GDK

In the following steps, $GDK_ROOT is the directory where you cloned GDK.

  1. Set up the GDK hostname.

  2. Add a GitLab Pages hostname to the gdk.yml:

    gitlab_pages:
  enabled: true         # enable GitLab Pages to be managed by gdk
  port: 3010            # default port is 3010
  host: pages.gdk.test  # the GitLab Pages domain
  auto_update: true     # if gdk must update GitLab Pages git
  verbose: true         # show more information in the logs

Running GitLab Pages with GDK

After these configurations are set, GDK manages a GitLab Pages process, giving you access to it with commands like:

  • Start: gdk start gitlab-pages
  • Stop: gdk stop gitlab-pages
  • Restart: gdk restart gitlab-pages
  • Tail logs: gdk tail gitlab-pages

Running GitLab Pages manually

You can also build and start the app independent of GDK processes management.

For any changes in the code, you must run make to build the app. It's best to just always run it before you start the app. It's quick to build so don't worry!

make && ./gitlab-pages -config=gitlab-pages.conf

Building GitLab Pages in FIPS mode

FIPS_MODE=1 make && ./gitlab-pages -config=gitlab-pages.conf

Creating GitLab Pages site

To build a GitLab Pages site locally you must configure gitlab-runner

Check the user manual.

Enabling access control

GitLab Pages support private sites. Private sites can be accessed only by users who have access to your GitLab project.

GitLab Pages access control is disabled by default. To enable it:

  1. Enable the GitLab Pages access control in GitLab itself, which can be done by either:

    • If you're not using GDK, editing gitlab.yml:

      # gitlab/config/gitlab.yml
pages:
  access_control: true

    • Editing gdk.yml if you're using GDK:

      # $GDK_ROOT/gdk.yml
gitlab_pages:
  enabled: true
  access_control: true

  2. Restart GitLab (if running through the GDK, run gdk restart). Running gdk reconfigure overwrites the value of access_control in config/gitlab.yml.

  3. In your local GitLab instance, in the browser go to http://gdk.test:3000/admin/applications.

  4. Create an Instance-wide OAuth application with the api scope.

  5. Set the value of your redirect-uri to the pages-domain authorization endpoint

    • http://pages.gdk.test:3010/auth, for example
    • The redirect-uri must not contain any GitLab Pages site domain.

  6. Add the auth client configuration:

    • With GDK, in gdk.yml:

      gitlab_pages:
  enabled: true
  access_control: true
  auth_client_id: $CLIENT_ID           # the OAuth application id created in http://gdk.test:3000/admin/applications
  auth_client_secret: $CLIENT_SECRET   # the OAuth application secret created in http://gdk.test:3000/admin/applications

      GDK generates random auth_secret and builds the auth_redirect_uri based on GitLab Pages host configuration.

    • Without GDK, in gitlab-pages.conf:

      ## the following are only needed if you want to test auth for private projects
auth-client-id=$CLIENT_ID                         # the OAuth application id created in http://gdk.test:3000/admin/applications
auth-client-secret=$CLIENT_SECRET                 # the OAuth application secret created in http://gdk.test:3000/admin/applications
auth-secret=$SOME_RANDOM_STRING                   # should be at least 32 bytes long
auth-redirect-uri=http://pages.gdk.test:3010/auth # the authentication callback url for GitLab Pages

  7. If running Pages inside the GDK, you can use GDK's protected_config_files section under gdk in your gdk.yml to avoid getting gitlab-pages.conf configuration rewritten:

    gdk:
  protected_config_files:
  - 'gitlab-pages/gitlab-pages.conf'

Linting

# Run the linter locally
make lint

Testing

To run tests, you can use these commands:

# This will run all of the tests in the codebase
make test

# Run a specfic test file
go test ./internal/serving/disk/

# Run a specific test in a file
go test ./internal/serving/disk/ -run TestDisk_ServeFileHTTP

# Run all unit tests except acceptance_test.go
go test ./... -short

# Run acceptance_test.go only
make acceptance
# Run specific acceptance tests
# We add `make` here because acceptance tests use the last binary that was compiled,
# so we want to have the latest changes in the build that is tested
make && go test ./ -run TestRedirect