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/

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