You host your blog on an own server and want to protect it with a password? Unlike hosting it on GitLab Pages, GitLab’s built-in access mechanisms are not available. For Apache servers you can use BasicAuth to set up a simple password protection. This requires only two files on your server: .htaccess and .htpasswd. In this article you will learn what these files do and how to create them with the correct content.

BasicAuth provides only basic protection and by itself is not very secure. Credentials are sent with every request unencrypted (only Base64-encoded) and can be easily intercepted without HTTPS. Therefore always use an encrypted connection (SSL/TLS).

TL;DR

Here are the most important steps to set up password protection for your blog on an Apache server. You can find detailed explanations further down in the article.

  1. Log in to your server and create the .htpasswd file there with the desired credentials.

    1. Create the file outside the directory where your website is deployed.

    2. Command to create it: htpasswd -cB /absolute/path/to/.htpasswd USERNAME

    3. Command to add another user: htpasswd -B /absolute/path/to/.htpasswd ANOTHER_USER

  2. Store the absolute path to the .htpasswd file as the variable (DEP_HTPWD) in your .gitlab-ci.yml.

    1. Get the correct path for example with: realpath /absolute/path/to/.htpasswd (this resolves symlinks)

    2. Make sure the user under which Apache runs has access to that path.

  3. Commit and push your changes to the repository.

  4. Test the password protection in your browser - done!

This procedure applies to Apache servers. Other web servers like Nginx also support BasicAuth (for example via the auth_basic directive in the configuration).

Detailed steps

The following explains in detail the individual steps to set up a simple password protection for your blog on an Apache server.

Basically, you need two files on your Apache server:

  • The .htaccess file enables password protection for the desired directory.

  • The .htpasswd file contains the credentials (username(s) and hashed password(s)).

In this article I show only one way to create and deploy these files. You can adapt the solution to your requirements and circumstances (for example how the files are created, where they are stored, how often they are deployed, etc.).

1. Creating the .htpasswd file

The .htpasswd file contains the credentials for the password protection - one line per user, consisting of the username and the hashed password. You can use the htpasswd tool from the apache2-utils package [1] to create and manage the file. Create the file preferably directly on the Apache server - the htpasswd tool is usually available there. Alternatively, you can create the file locally and then upload it to the server.

Command to create the .htpasswd file (replace USERNAME with the desired username):
htpasswd -cB /absolute/path/to/.htpasswd USERNAME

  • The -c option (for "create") creates the file. Use it only when creating the file for the first time, because it overwrites the file.

  • To add additional users, omit the -c option.

  • The -B option uses bcrypt to securely hash the password (recommended). By default, MD5 is used.

Be aware that usernames are case-sensitive. Therefore anna and Anna are two different users.

Create the .htpasswd file outside the directory where you will deploy the website. This reduces the risk that the credentials become publicly accessible together with the website.

Then configure the absolute path to the .htpasswd file as a variable (e.g., DEP_HTPWD) in your .gitlab-ci.yml. This value will be needed later to create the .htaccess file. Extend your deploy_to_own_server job in .gitlab-ci.yml as follows:

variables:
  ## For password protection on Apache servers
  ## Absolute path to the .htpasswd file on the server
  DEP_HTPWD: "/absolute/path/to/htpasswd_files/.htpasswd_file_a"

2. Creating the .htaccess file

The .htaccess file enables and configures the password protection. The content of the .htaccess file could look like this:

AuthType Basic(1)
AuthName "Access restricted to authorized users"(2)
AuthUserFile /absolute/path/to/.htpasswd(3)
Require valid-user(4)
1 The authentication method "Basic" is used. Username and password are sent with every request.
2 Name of the authentication realm shown to the user. The realm mainly affects credential caching in the browser.
3 Absolute path to the .htpasswd file on the server.
4 Only authenticated users are granted access to the protected area.

Since you stored the absolute path to the htpasswd file in the variable DEP_HTPWD, you can generate the .htaccess file during deployment. Add the following code to the deploy_to_own_server job in .gitlab-ci.yml:

script:
  - |
    cat > public/.htaccess <<HTACCESS
    AuthType Basic
    AuthName "Access restricted to authorized users"
    AuthUserFile ${DEP_HTPWD}
    Require valid-user
    HTACCESS

Because scp does not transfer hidden files by default, you must explicitly ensure their transfer. Thus, add public/.htaccess explicitly to the list of files to be transferred.

    - scp -P${DEP_PORT} -r public/.htaccess public/* ${DEP_USER}@${DEP_HOST}:${DEP_DIR}/_tmp

3. Transferring the files

  • Run the deployment process to transfer the files to the server.

  • Therefore, commit the changes and push them to your Git repository.

4. Testing the password protection

  • After a successful deployment, open your blog in the browser.

  • You should now be prompted to enter a username and password.

  • Verify that access is denied without valid credentials.

You might not be prompted for username and password because your browser cached credentials from a previous authentication. In that case, test access in a private/incognito browser window.

Notes and further resources

1. If apache2-utils is not installed, you can usually install it with your distribution’s package manager. For Debian-based systems like Ubuntu the command is sudo apt-get install apache2-utils