Faircamp

Self-hosting a Faircamp instance.

I’ve set up a self-hosted Faircamp instance to allow people to listen, download, and share my music.

You can find my instance at https://music.theargentgrub.co.uk/

I build the site, using Linux, with the help of Docker and the Docker image provide by n3wjack and then deploy it to my own server.

This is how I do it…

Initial set up

Make a directory for it to all sit in, and a directory within that for the data

mkdir faircamp
mkdir faircamp/data

Place the music albums directly in the data directory.

When I first started I had a folder with just the .flac files and the album artwork for each release.

However in order to have information about each track, I’ve needed to re-order the albums so that each track has it’s own directory under the main album directory, so that it can have it’s own track.eno file. e.g.

data/
    - Field Recordings/
        - release.eno
        - cover.jpg
        - Track One/
            - track-one.flac
            - track.eno
        - Track Two/
            - track-two.flac
            - track.eno
    - catalog.eno
    - profile-image.jpg

Generate the site for the first time

The above is (more than) enough to generate a Faircamp static site, so I do that by running

 cd faircamp
 docker run -ti -v ./data:/data --rm n3wjack/faircamp

This creates a .faircamp_build and a .faircamp_cache directory in the data directory.

Browsing the site on my local machine

I had trouble getting a local version to browse (I was trying it with –preview as an ‘extra argument’ as documented on GitHub and in the Faircamp manual) so decided to run up a nginx webserver with docker instead.

In the faircamp directory I have a docker-compose.yml file and a .env file:

.env

COMPOSE_PROJECT_NAME=faircamp
NGINX=nginx

docker-compose.yml

services:
  nginx:
    image: ${NGINX}
    volumes:
    - ./data/.faircamp_build:/usr/share/nginx/html
    ports:
    - "8080:80"

Running

docker-compose up 

You can then view the site on http://localhost:8080

Rebuild and refresh the site

Once the site is built there are edits to e.g. .eno files to do, so the site needs to be rebuilt.

If I simply run the Faircamp docker image again, the nginx server doesn’t like it for some reason so I need to restart that service as well. It can be done in one command:

docker run -ti -v ./data:/data --rm n3wjack/faircamp && docker restart faircamp-nginx-1

Adding my site to the Faircamp Webring

The Faircamp Webring is a way for people using Faircamp to discover other artists.

I added the required code to my build following the Faircamp Webring How To Join instructions.

Pre-Deployment

Before Faircamp v1.4, before I pushed the site to the server, I needed to inject my Matomo analytics script to each page of the generated site. This was done with a script to inject google analytics into a Faircamp build that I got from Faircamp user Márk Horváth.

However, since Faircamp v1.4 I can now use the site-metadata option in catalog.eno

Deploy to the live server

I have Docker running on the live server.

I also have Cloudflare managing my DNS and secure certificates.

I use traefik on the server to manage routing all my docker containers to the outside world.

And I can access the server via SSH

I guess that set up is fairly specific, but for the purposes of deploying the site, or an update to the site, once it is running on the server I can update the site with rsync over ssh to the server. So to send the Faircamp files to the server

## NB FROM INSIDE THE faircamp directory
rsync -avzh  data/.faircamp_build <user>@<server ip>:/path/to/faircamp/data/

Redeploy to the live server after an update

I’ve recently applied an update and noticed that some of the audio files were regenerated so in order to properly sync the live files with the new files it’s necessary to delete some from the server, so:

## NB FROM INSIDE THE faircamp directory
rsync -avzh  data/.faircamp_build <user>@<server ip>:/path/to/faircamp/data/ --delete

Version Control

I want to keep all the things that I need to build the site in version control - .eno files, images, directory structure, and the files I use to work with the site like docker-compose.yml, and the injection script BUT I’m not too bothered about the actual .flac files - and I don’t really want them to end up in e.g. GitLab.

My .gitignore file in the faircamp directory looks like this:

*.flac
*.mp3
*.ogg
*.pdf

.faircamp_build
.faircamp_cache

.env

I also need to send some of the ‘working’ files up to the server as well so I have an exclude file that I use with rsync

exclude_list.txt
docker-compose.traefik.yml
inject-matomo-analytics.sh
matomo.html
README.md
data/
.git
.gitignore

So if I want to update my docker-compose.yml file (and a couple of others, e.g. .env) on the server I can run:

## NB FROM OUTSIDE THE faircamp directory
rsync -avzh --exclude-from='faircamp/exclude_list.txt' faircamp/ <user>@<server_ip>:/path to/faircamp