Hosting an instance like #Mastodon or #Pixelfed under #Docker makes you deal with Docker images every time a new version comes or simply when you apply any customization, like changing the logos or so on. The process is not really complicated but there are some caveats that keep an eye on.

Here I focus on my Pixelfed instance at LaDragonera.com.

0. Overview

In this post I will go through the process of generating a new Docker image from the instance code, keeping some simple customizations I have over the instance. I split the article in the following sections:

1. [Optional] Update the repository

2. Build the image

3. Push the image

4. Use the new image

5. Wrapping up

0.1. Assumptions

• You're already SSH-ed into the host.

• You run all commands inside the Pixelfed's cloned directory. In my case:

  cd ~/pixelfed

1. [Optional] Update the repository

May be the case (actually one of the main use cases) that you want to build a new Docker image because a new version was released. Usually this new version is defined by a tag in the repository.

Taking this as an example, you may want to update your cloned repository first. Could also be that you personalized your instance with some statics like different logos and so on. Let's take care of it in these subsections.

1.1. Keep your customizations out

Assuming that the customizations are some new or changed files in the repository, we can just keep them temporary secured out of the way:

Git stash everything in the repo

git stash

1.2. Update the repository

Now that the repository is clean from customizations, let's bring the updates. At the moment of this article, Pixelfed works in a dev branch. We could just bring all changes with:

git pull

To be in the safe side, we only want changes that comes under a version tag. At the moment of this article, it was the 0.11.8

Checkout the repository code under the desired tag. This will bring the repository limited to the code under a certain tag.

git checkout v0.11.8

1.3. Update's side work

New versions usually come with extra work to be done, like applying the migrations. Make sure that you read the documentation regarding the new version and apply the needed changes.

Run migrations (DB and code are directly related):

docker-compose exec app php artisan migrate --force

1.4. Re-apply customizations

Now that we have the new code, let's bring back the customizations like logos and so on that we kept temporarily out of the repo:

Bring the stashed changes:

git stash pop

2. Build the image

Now we build the image, that will be built on top of the current status of the repo.

Images should be created already with a local tag, so that later on we can recall on them. I use project:date as a tag for my local images.

Run the build command defining a tag and pulling from the oficial Dockerfile:

docker build . -t pixelfed:20230621 -f contrib/docker/Dockerfile.apache

3. Push the image

This is not a mandatory step, you can work with images built in local. Personally, I like to have the image delivered anywhere, for sharing and backup reasons, so I can really quick bring a service back. This will need that you have an account in Docker Hub and already created a repository there.

If you want to avoid this step, just jump to the next section and use the local tag pixelfed:20230621 wherever I use the remote tag arnaus/pixelfed:ladragonera_0.11.8

Images in the remote need to have a tag. We will create a new tag for the remote image based on the local image, and then push this image to the remote artifactory.

1. Login into Docker

   docker login

2. Run the build command defining a tag and pulling from the oficial Dockerfile.

   docker tag pixelfed:20230621 arnaus/pixelfed:ladragonera_0.11.8

3. Push the image to the artifactory.

   docker push arnaus/pixelfed:ladragonera_0.11.8

4. Use the new image

Now we want to go to our docker-compose.yml and change the image to be used to our newly pushed one:

1. Edit the docker-compose.yml file:

   nano docker-compose.yml

2. Under the app and worker services, change the value for the parameter image to now set arnaus/pixelfed:ladragonera_0.11.8

3. Save (ctrl+o) and exit (ctrl + x)

4. Restart the containers

   docker-compose up -d

5. Clear the cache

   docker-compose exec app php artisan cache:clear

At this point, the Pixelfed instance should be publishing the new image.

5. Wrapping up

This is the way I use to keep my Pixelfed instance up-to-date and also customized. The whole process just takes 15 minutes, including the building and pushing time.

Previous Post Next Post