Put a password on a site

$ grim server:auth shop --enable

The site is deployed and nobody outside the team should see it yet: a staging copy, a shop before its launch day, a client preview. grim server:auth puts the browser's own password prompt in front of the whole project, and takes it away again on the day it opens. The app is not involved. The prompt comes from nginx on the host, before a request reaches a container.

Usage

$ grim server:auth shop --enable                              # user admin, password generated
$ grim server:auth shop --enable --user=client --pass=s3cret  # your own pair
$ grim server:auth shop --disable                             # open to everyone again
$ grim server:auth shop --enable --env=staging                # the staging stack only

Run it from anywhere. The project must be in your ~/.grim/servers.json. Without --env it acts on the project's default environment, the first one you registered. One of --enable and --disable is required; with neither the command stops with Specify --enable or --disable.

Arguments and options

Enable or disable HTTP Basic Auth for a project

Usage

grim server:auth [--enable] [--disable] [--user USER] [--pass PASS] [--env ENV] [--] <project>

Arguments

Options

What it actually does

With --enable:

1. Settles the password. Without --pass it generates one of twelve characters and prints it.
2. Writes .htpasswd into the stack's directory on the server (/opt/shop, /opt/shop-staging for --env=staging). The hash is made there; only the hash is stored.
3. Rewrites the stack's nginx vhost with the password prompt on everything except /api/v1/healthcheck, so health checks and monitoring keep working without credentials. The vhost keeps every domain attached with grim server:add-domain and a certificate of your own, if the project has one.
4. Runs certbot again for the primary domain and every alias to put the HTTPS block back into the rewritten vhost, then reloads nginx. A project with its own certificate skips certbot: the certificate is already in the vhost.
5. Records the state in servers.json and prints Credentials: admin / ….

With --disable the vhost is rewritten without the prompt, certbot and the reload run the same way, and .htpasswd is removed.

Pitfalls

The password is shown once

Only its hash reaches the server and nothing is kept on your machine. Copy the Credentials line when it appears. A forgotten password is replaced by running --enable again, which also replaces the user: the file holds one pair at a time.

No certificate at all

Warning: no acme_email recorded; skipping SSL setup. Vhost is HTTP-only. appears on a server set up without an ACME e-mail and without a certificate of its own. It means what it says: the site answers on plain HTTP until grim server:setup records an e-mail and the command runs again.

Adding the project again switches it off

Any later run of grim server:add-project writes the vhost without the prompt. Enable it again afterwards.

After it finishes

Open the site in a private window. The browser asks for the pair before anything loads. API clients and webhooks that call the site from outside are asked too, and they fail with 401 until they send the credentials or the prompt is switched off.

Related spells