Fractal + Heroku + Basic auth

I’m currently experimenting with the rather excellent ’Fractal’ a powerful tool for building component libraries & styleguides.

As it’s for work and my employer being a government department I find myself having to be cautious about working in the open (at least in the initial stages of work). Mainly because we wouldn’t want citizens or fellow civil servants to find a trial service and believe it to be something they should use.

The quickest way to get a build of Fractal online is to use a service like Heroku which is very good but can be complicated for less experienced users (of which I count myself).

I’d shared the URL with immediate colleagues yet needed to retroactively add a form of ‘basic auth’ to keep the work private until we’re ready. Fractal doesn’t come with authentication out of the box so I needed to find a way to add it in. A bunch of googling and hair pulling later. Here is what to do for a quick and dirty way to get this up and running.


Assuming you have the following:

  • Heroku account and heroku 'app’ (sometimes referred to as a dyno) - Setup ready to build your Fractal instance onto.
  • You have installed the Heroku toolbelt locally
  • Fractal building correctly to a 'build’ or distribution directory.

These instructions are specifically for mac users.

Step 1 - Set the custom 'build pack’

We’re going to use a heroku 'build pack’ that has been modified to handle serving static content but with the ability to put it behind basic auth protection.

There is a command within the heroku toolbelt to set the buildpack and you can set it to a custom pack. In terminal type the following:

$ heroku buildpacks:set

It should tell you that it has been set.

Buildpack set. Next release on [YOUR-APP-NAME] will use Rungit push heroku masterto create a new release using this buildpack.

Step 2 - Add a config file to your root

In the root of your project, you will need to create a file called static.json:

That file will tell which directory to make the document-root. In our case it will be our Fractal build directory (sadly this means you will need to commit it to git). I’ve called mine 'build’. Then a second property to tell it to use basic-auth. See below.

  "root": "build/",
  "basic_auth": true

Add this to your git repository.

Step 3 - Set your username

To set your username and password you will need to run some terminal commands to hash your password and then set it as a configuration variable within heroku.

Decide upon a username and password. To set the username, switch to your fractal directory with terminal and enter the following command replacing username with yours.

$ heroku config:set BASIC_AUTH_USERNAME=username

All being well you will see something like:

Setting BASIC_AUTH_USERNAME and restarting ⬢ your-app-name... done

Step 4 - Hash your password

Now you need to hash your password. To do so run the following command in terminal:

openssl passwd -apr1

It will ask you type the password you want to hash (not your machine password) twice. Then it will output the hashed password to the terminal like so:

$ openssl passwd -apr1
Verifying - Password:

Copy the hashed password to your clipboard.

Step 5 - Set your password

Set your password as a heroku config var for your fractal application like so

heroku config:set BASIC_AUTH_PASSWORD='$apr1$Raj6GPh$PGGYHuiL8Va76zCWQy4Im0'

Pasting your password intead of this demo password hash you can see in the above example.

Step 6 - Build your Fractal & Deploy

Build your fractal, I’m using gulp but you could just run:

fractal build

Typically to deploy you will jush the branch to the heroku remote with a command like so:

$ git push heroku master
Initializing repository, done.
updating 'refs/heads/master'

That should be it. Access the Heroku url and see if you get a basic auth username/password dialogue.

If you have problems. Log into heroku and deploy via the interface. You should see something like this in the build log:

-----> Static HTML app detected
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
38k  100  838k    0     0  14.3M      0 --:--:-- --:--:-- --:--:-- 14.6M
-----> Installed directory to /app/bin
-----> Discovering process types
       Procfile declares types     -> (none)
       Default types for buildpack -> web
-----> Compressing...
       Done: 11.6M
-----> Launching...
       Released v26 deployed to Heroku

Also check your username and password are in the config vars within heroku by going to settings -> reveal config vars.

I'm designing this blog "live". I believe that coding in the open promotes sharing, feedback and learning. Occasionally things will change and possibly break but that's ok. You can let me know.

Feel free to browse the source code and commit history