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.
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:
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.
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 http://127.0.0.1:7777;<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.
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.
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.
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.
Fill in both the Project Name and Project Description textboxes with your repository details, then click Apply Changes to save it.
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 (.).
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.
Select Users on the administrator’s control panel.
Click Add to create a new user for your repository.
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.
Go back to your local terminal, then run the following command:
fossil push https://YOUR-USERNAME@SUBDOMAIN.YOUR-ROOT.DOMAIN
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.
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
