June 18, 2024

How to Install Fossil Version Control System in Linux

A photograph of a computer screen displaying JavaScript code.

Fossil is a powerful version control system (VCS) for Linux. It is an alternative to Github, but unlike Git, it works by providing a complete suite of tools for creating, modifying, and even sharing your repository online. This article will show you how to install and deploy Fossil on Ubuntu Linux.

Why Use Fossil Over Git

One of the biggest selling points of Fossil is that it’s an all-in-one suite for managing your source code online. This makes it incredibly useful for users who just want to share a single repository with other people without creating either a Github or Gitlab account.

Aside from that, Fossil is also highly flexible and incredibly easy to self-host. It can run either as a single static binary in your system or in a self-contained Docker container. As a result, it’s very simple to get into Fossil and adapt it for your own needs.

While Fossil and Git share the same operating syntax, Fossil provides additional features that are hard to implement in Git. For example, Fossil avoids the “detached HEAD” issue by providing an internal database that tracks the references between previous and future commits. As a result, Fossil repos are more seamless and trouble-free compared to Git.

Another advantage of Fossil over Git is that it requires fewer dependencies and memory to run while providing features right out of the box. A Fossil instance has its discussion board, wiki, and issue tracker. This makes Fossil an integrated solution for anyone who wants a “no-fuss” environment for developing and publishing code.

Good to know: learn some of the best Git hooks to manage your repository.

Obtaining Fossil’s Prerequisites and Docker

The first step in deploying Fossil is to obtain the repository files for Docker. To do that, fetch the signing key for the Docker project:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg<br>sudo chmod a+r /etc/apt/keyrings/docker.gpg

Create a new file under “/etc/apt/sources.list.d.” This will contain the repository link where Ubuntu will fetch the Docker packages:

sudo nano /etc/apt/sources.list.d/docker.list

Paste the following code inside your new repository file:

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable

Save your Docker repository file, then install the core snap package:

Download the Certbot snap package from the Electronic Frontier Foundation:

sudo snap install certbot --classic

Run the following command to refresh your system’s package listings:

sudo apt update && sudo apt upgrade

Install Docker and Nginx along with their dependency packages:

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin docker-buildx-plugin nginx

Building and Installing Fossil in Linux

Navigate to the download page for Fossil, then select the source tarball for the latest stable release. In my case, I will download version 2.23 of Fossil.

A screenshot highlighting the link for the latest stable release for Fossil.

Move the source tarball to your home directory, then extract it:

mv ~/Downloads/fossil-src-2.23.tar.gz<br>tar xvzf ~/fossil-src-2.23.tar.gz

Go inside your tarball’s folder, then open Fossil’s Dockerfile using your favorite text editor:

cd ~/fossil-src-2.23<br>nano ./Dockerfile

Scroll down to the bottom of the file, then add the following before the "--user", "admin" ] line:

A terminal highlighting the

Save your modified Dockerfile, then build your container image:

sudo docker build -t fossil .

Running Fossil and Creating an SSL Reverse Proxy

You now have a new instance of Fossil VCS running as a Docker container on your server. To access it, you need to encrypt any external connections to Fossil.

To start, create a new DNS “A” record pointing to the IP address of your Fossil server.

A screenshot showing the A DNS record for Fossil.

Use your favorite text editor to create a new site configuration file for your Fossil instance:

sudo nano /etc/nginx/sites-available/fossil-scm

Paste the following block of code inside your new site configuration file:

server {<br><br>        server_name SUBDOMAIN.YOUR-ROOT.DOMAIN;<br><br>        location / {<br>                proxy_pass;<br>                proxy_http_version 1.1;<br>                proxy_set_header Upgrade $http_upgrade;<br>                proxy_set_header Connection "upgrade";<br>                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;<br>                proxy_set_header Host $host;<br>        }<br>}

Replace the server_name variable with your subdomain for Fossil.

A terminal showing a reverse proxy site config file in Nginx.

Create a symbolic link for your site configuration file to “/etc/nginx/sites-enabled/”:

sudo ln -s /etc/nginx/sites-available/fossil-scm /etc/nginx/sites-enabled/

Start your system’s Nginx daemon using systemctl:

sudo systemctl enable --now nginx.service<br>sudo systemctl reload nginx.service

Start your new Fossil Docker image by running the following command:

sudo docker run \<br>    --publish 7777:8080 \<br>    --name fossil \<br>    --cap-drop AUDIT_WRITE \<br>    --cap-drop CHOWN \<br>    --cap-drop FSETID \<br>    --cap-drop KILL \<br>    --cap-drop MKNOD \<br>    --cap-drop NET_BIND_SERVICE \<br>    --cap-drop NET_RAW \<br>    --cap-drop SETFCAP \<br>    --cap-drop SETPCAP \<br>    fossil

Open a new Tmux panel by pressing Ctrl + B, then C. Inside, run the following command to request an SSL certificate from Certbot:

sudo certbot --nginx -d fossil-scm.myvpsserver.top

Test if your Fossil instance is accessible over the internet by navigating to your subdomain.

A screenshot showing the landing page for a freshly installed Fossil instance.

Good to know: learn how you can create simple webpages with automatic HTTPS using Caddy.

Creating Your First Fossil Repository

With Fossil up and running in your Linux server, you can now configure your new instance. Click the setup/config link under the Home section.

A screenshot highlighting the "setup/config" link on Fossil's default landing page.

Provide the administrator account’s details, then click log in. You can find the password for the admin account in the output log of your Docker container.

A screenshot highlighting the random password for the admin account.

Fill in both the Project Name and Project Description textboxes with your repository details, then click Apply Changes to save it.

A screenshot highlighting the "Apply Changes" button for Fossil's initial config.

Cloning and Using Your Fossil Repository

To use your new code repository, you need to first create a copy of it on your machine. To do that, install a local version of Fossil on your Linux desktop:

Pull the entire repository to your machine and go inside its repository folder:

fossil clone https://SUBDOMAIN.YOUR-ROOT.DOMAIN<br>cd ./YOUR-REPO-NAME

Add your initial files, then commit the changes to your Fossil repository:

nano ./sample.file<br>fossil add ./sample.file<br>fossil commit

Provide the details of your initial commit, then save it by creating a new line that starts with a period (.).

A terminal showing the commit message format for Fossil.

FYI: learn the basics of code management by creating your own Git repository.

Pushing Local Changes to Your Remote Fossil Repository

By default, Fossil doesn’t provide any write permissions to its remote repositories. Any changes you make to your local repository will stay there and not reflect in your Fossil instance.

To fix this, go to your Fossil instance’s web interface then login as the administrator account.

Click the Admin category on the dashboard’s top menu.

A screenshot showing the location of the

Select Users on the administrator’s control panel.

A screenshot showing the "Users" category in the Administrator's console.

Click Add to create a new user for your repository.

A screenshot showing the location of the

Provide a username and a password for your new user.

Tick the Developer checkbox on the Capabilities category, then click Apply Changes to save your new user.

A screenshot showing the default committer setup for a new Fossil user.

Go back to your local terminal, then run the following command:


Note: you can also fetch new changes from your remote Fossil repository by running fossil pull.

Type the password for your Fossil user, then press Enter to push the local changes to your remote repository.

Confirm that your remote Fossil repo has received your local commit by navigating to its web interface.

A screenshot showing the sample commit file in the self-hosted Fossil instance.

Installing and deploying your own Fossil version control system is just the first step in taking back control of your online data. Learn how you can secure your online communications by hosting your own email aliases server with SimpleLogin.

Image credit: Panjak Patel via Unsplash. All alterations and screenshots by Ramces Red.

Subscribe to our newsletter!

Our latest tutorials delivered straight to your inbox

Ramces Red

Ramces is a technology writer that lived with computers all his life. A prolific reader and a student of Anthropology, he is an eccentric character that writes articles about Linux and anything *nix.

Leave a Reply

Your email address will not be published. Required fields are marked *