Merge branch 'enable-access-control-dev-guide' into 'master'

Add development guide inside the GDK

See merge request gitlab-org/gitlab-pages!426

1 files changed, 137 insertions, 0 deletions

diff --git a/doc/development.md b/doc/development.md
index e329b105..9eb4cf39 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -43,6 +43,143 @@ This is because `/etc/hosts` does not support wildcard hostnames.
 An alternative is to use [`dnsmasq`](https://wiki.debian.org/dnsmasq) to handle wildcard hostnames.
 
 
+### Enable access control
+
+Pages access control is disabled by default. To enable it:
+
+1. Modify your `config/gitlab.yml` file:
+
+   ```rb
+   pages:
+     access_control: true
+   ```
+
+1. Restart GitLab (if running through the GDK, run `gdk restart`). Note that running
+   `gdk reconfigure` overwrites the value of `access_control` in `config/gitlab.yml`.
+
+1. In your local GitLab instance, navigate to `/admin/applications`.
+1. Create an [OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html#add-an-application-through-the-profile).
+1. Set the value of your `redirect-uri` to the `pages-domain` authorization endpoint (for example
+   `http://192.168.1.135.nip.io:8090/auth`).
+1. Add these lines to your `gitlab-pages.conf` file:
+
+   ```conf
+   ## the following are only needed if you want to test auth for private projects
+   auth-client-id=$CLIENT_ID # generate a new OAuth application in http://127.0.0.1:3000/admin/applications
+   auth-client-secret=$CLIENT_SECRET # obtained when generating an OAuth application
+   auth-secret= $SOME_RANDOM_STRING # should be at least 32 bytes long
+   auth-redirect-uri=http://192.168.1.135.nip.io:8090/auth
+   ```
+
+1. If running Pages inside the GDK, you can add the `gitlab-pages.conf` file to the
+   `protected_config_files` section under `gdk` in your `gdk.yml` file:
+
+   ```yaml
+   gdk:
+     protected_config_files:
+     - 'gitlab-pages/gitlab-pages.conf'
+   ```
+
+## Developing inside the GDK
+
+This is an example of developing GitLab Pages inside the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit):
+
+1. [Prepare your GDK environment](https://gitlab.com/gitlab-org/gitlab-development-kit#how-to-install-gdk).
+   In the steps that follow, `$GDK_ROOT` is the directory where you cloned the GDK.
+1. Add the following lines to your `gdk.yml` file:
+
+   ```yaml
+   # You can use dnsmasq to use a different hostname https://www.tecmint.com/setup-a-dns-dhcp-server-using-dnsmasq-on-centos-rhel/
+   hostname: 127.0.0.1.nip.io
+   gitlab_pages:
+     auto_update: true
+     enabled: true
+     port: 3010
+     secret_file: $GDK_ROOT/gitlab-pages-secret # run make gitlab-pages-secret in your $GDK_ROOT
+     verbose: true
+     host: pages.127.0.0.1.nip.io
+
+   # enable Object Storage to use the latest features
+   object_store:
+     enabled: true
+     port: 9000
+
+   # only needed if you are using ssh
+   repositories:
+     gitlab_pages: git@gitlab.com:gitlab-org/gitlab-pages.git
+
+   # add this line to keep changes to your gitlab-pages.conf file intact after running `gdk reconfigure`
+   gdk:
+     protected_config_files:
+     - 'gitlab-pages/gitlab-pages.conf'
+
+   sshd:
+     enabled: true
+     listen_port: 2222
+     user: your-uuser
+   ```
+
+1. Reconfigure the GDK by running `gdk reconfigure`.
+1. Go to `$GDK_ROOT/gitlab-pages`:
+
+   ```sh
+   cd $GDK_ROOT/gitlab-pages
+   ```
+
+   Note that running `gdk reconfigure` overrides your `gitlab-pages.conf` file and sets the default
+   flags. Make sure you add the file to the `protected_config_files:` YAML node in your `gdk.yml`
+   file.
+
+1. Create or edit the file `$GDK_ROOT/gitlab-pages/gitlab-pages.conf` to add these lines:
+
+   ```conf
+   # the port where you want Pages to listen to, must match the port in `gdk.yml`
+   listen-http=:3010
+   artifacts-server=http://127.0.0.1.nip.io:3000/api/v4
+   pages-root=$GDK_ROOT/gitlab/shared/pages # absolute path inside $GDK_ROOT
+   pages-domain=pages.127.0.0.1.nip.io
+   internal-gitlab-server=http://127.0.0.1.nip.io:3000
+   api-secret-key=$GDK_ROOT/gitlab-pages-secret # run make gitlab-pages-secret in your $GDK_ROOT
+   domain-config-source=gitlab # preferred way, requires api-secret-key and internal-gitlab-server
+   log-verbose=true
+   ## the following settings are only needed if you want to test auth for private projects
+   auth-client-id=$CLIENT_ID # generate a new OAuth application in http://127.0.0.1.nip.io:3000/admin/applications
+   auth-client-secret=$CLIENT_SECRET # obtained when generating an OAuth application
+   auth-secret= $SOME_RANDOM_STRING # should be at least 32 bytes long
+   auth-redirect-uri=http://pages.127.0.0.1.nip.io:3010/auth
+   ```
+
+   You can define any flags available in [`main.go`](https://gitlab.com/gitlab-org/gitlab-pages/-/blob/ec16301b72b5d8370ccdcd86088440cca409cd8b/main.go#L40).
+
+1. Start developing!
+1. To test your changes manually you can run:
+
+   ```sh
+   # Inside $GDK_ROOT/gitlab-pages
+   $ make
+   $ gdk restart gitlab-pages
+   $ gdk tail gitlab-pages
+
+   # or one-liner
+   make && gdk restart gitlab-pages && gdk tail gitlab-pages
+   ```
+
+1. Alternatively, you can run Pages manually:
+
+   ```sh
+   # Inside $GDK_ROOT/gitlab-pages
+   $ gdk stop gitlab-pages
+   $ make # calls go build in this project and creates a `gitlab-pages` binary under bin/
+   # start daemon manually with a config
+   $ ./bin/gitlab-pages -config gitlab-pages.conf
+   ```
+
+1. Create a project in your GDK and deploy a Pages project. For instructions, see
+   [Create a GitLab Pages website from scratch](https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html).
+1. To deploy your Pages site, you must [configure GitLab Runner in your GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/runner.md).
+1. Visit your project URL. You can see the URL under **Settings > Pages** for your project, or
+   [`http://127.0.0.1.nip.io:3000/user/project-name/pages`](http://127.0.0.1.nip.io:3000/user/project-name/pages).
+
 ## Linting
 
 ```sh