Setting up fossil

I have decided to start working on a game and want to write down what I do as a way of reinforcing the things that I learn.

The obvious first step for every project is buying a domain setting up the entire project workspace before even knowing what the project may look like.

For my personal projects, fossil has been my favorite scm for a while, so I will step you through the basic setup steps I need to do to get the project going.

Creating the repository

Opposing to git and its .git directory, fossil repositories are not stored in the project workspace, but in any other directory on your machine. I personally am using ~/fossils as a central place to drop all my repositories into.

So to create a new repository for my game, I simply run the following:

fossil init ~/fossils/game.fossil

This creates a game.fossil file, which in itself is an SQLite database. You could choose any extension you like, something along the lines of .fossil is most likely a reasonable approach though.

Setting up the workspace

A blank fossil repository does not do a lot for us. We could already edit some metadata and settings, but I prefer to first set up the workspace.

For this, I create an empty directory in my projects space and check it out:

mkdir ~/Projects/game
cd ~/Projects/game

Next, I need to open the repository in this directory, essentially linking them to each other.

fossil open ~/fossils/game.fossil

This is it. Any file in this directory can now be versioned by fossil.

Configuring the repository

The repository as it stands now is set up with all defaults. It is completely usable as it is, but there are a few changes I like to make.

I am using the ui to do these changes:

fossil ui

After that, I select Admin in the menu to see all configuration pages.

General configuration

First, I click the link to Configuration and give my project a name, and if necessary a short description.

Next, I update the links that should be displayed in the main menu. These defaults can be found in a larger textarea when scrolling down.

Home      /home        *              {}
Timeline  /timeline    {o r j}        {}
Files     /dir?ci=tip  oh             desktoponly
Branches  /brlist      o              wideonly
Tags      /taglist     o              wideonly
- Forum     /forum       {@2 3 4 5 6}   wideonly
- Chat      /chat        C              wideonly
Tickets   /ticket      r              wideonly
- Wiki      /wiki        j              wideonly
Admin     /setup       {a s}          desktoponly
Logout    /logout      L              wideonly
Login     /login       !L             wideonly

As the project is a private and personal project, I won't need collaboration tools like the forum or the chat.

The wiki in itself is a useful feature, which I am using for other projects - but I decided to try out and place docs and wiki into the repository, so it is versioned together with the code.

We may reintroduce this menu entry later, but at this point I don't think that I will need it.

After all these changes, it is time to hit Apply changes to be finished with this page.

Going private

The permission for accessing the repository are currently very lash. This is not a problem right now - the repository exists only locally. If I want to push it to my fossil server later though, I need to close it down to keep my code and ideas private.

Fossil has a neat and helpful page for doing this, going back to the Admin-Page and then selecting Security Audit.

Here, fossil displays some general information on security related settings to you. The first line offers me to take the repository private, which I do. This locks any external access to the repository from unauthenticated users.

Setting up a password

During repository creation, the CLI displayed an admin password, which I ignored earlier. If I want to be able to log into the repository on my remote server later, I need to set a new password.

To do this, I once again navigate to the Admin page and then select Users.

This page shows a list of existing users (marv) and four default roles. Looking at this, I do not remember when and where I set marv to be the default user of a repository, so your experience may differ.

Next I select marv to get to the details of this user.

I won't go into detail of all the options, but generally, a user with the capability Setup can do virtually everything.

Here I set a new password for my user and once again Apply Changes.

Uploading the repository

As stated earlier, I generally do back up my repository, but I feel safer when hosting it somewhere remotely aswell.

I am hosting my repositories on a cheap Hetzner Cloud Server, the smallest is more than enough to get fossil and a few other small projects running behind a docker reverse proxy. I may or may not safe some money here aswell with Hetzner being my employer.

I don't want to go to deep into the details of my setup here though. In short:

I have a reverse proxy that routes traffic to various different Docker containers.

One of these containers is running fossil and its server command. The container has access to a cloud volume that is attached to the server which contains all repositories that I am hosting.

Long story short, next step is rsyncing the repository file to the remote server:

rsync ~/fossils/game.fossil marv@server:/mnt/HC_Volume_1333337/repositories

Because I screwed up permissions when setting up the server, the last step for me here is to ssh into the vm and give the user running the containers ownership on the repository file.

To simplify that process, I just do that for every repository at once:

chown -R docker-user /mnt/HC_Volume_1333337/

Linking repositories

The repository is online now, but the local one does not know about the remote one. To connect the two, I run the fossil sync command:

fossil sync "https://marv@remote.url/game"

It will prompt me for the password of the user marv, which we set earlier. After pasting and confirming that fossil shall remember it, our repositories are now connected.

The first commit

I am writing this blog for some online platform, but prefer to use vim bindings and markdown to write text. Because of that, I decided to add these posts as markdown to the repository. This very text will be the first artifact that is committed to fossil.

This markdown file is more or less ready, but it includes three screenshots. Images are binary files, I do not need to diff their content in fossil, but would like to keep them versioned. To give fossil a hint about this, I am creating a file in my workspace: .fossil-settings/binary-glob with the following content:

docs/blog/assets/*

This will now tell fossil to handle all files in the assets directory as binaries. They will still be versioned, but fossil won't attempt to diff their content.

Before I can commit all my new files, I need to add them to the repository:

fossil add .fossil-settings docs

Do not confuse this with staging files in git. In fossil, you have to explicitly add files to the repository for them to be tracked and versioned, as opposed to git where all files in your workspace are implicitly added to your repository and will be tracked right way.

To commit these files, I run the commit command, using the shorthand ci and tagging it with blog to make it easier in the future to find all commits that included a blog entry:

fossil ci --tag blog

You can - similar to git, add a commit message through the cli, but I prefer using vim to write mine, so I omit the the flag for that.

This will now include all files that have been changed, created or deleted in the commit. This is another crucial difference to git: There is no staging. Whenever you commit, you commit the current state of changes. Of course you are able to pass filenames to commit single files or selected directories, but a concept that you are required to stage files before committing does not exist in fossil.

After finishing the commit message, fossil will automatically sync the commit to the server, no need to push - we are done.

If we run fossil ui, or check out the remote, we can see our commit in the timeline:

Conclusion

While I have been spending a long time writing this blog post, setting up a project in fossil only takes me a few minutes. With its sane defaults, fossil helps to get started right away.

I will do some more personalization on this project in the future, which I will document here aswell.

Thanks for reading, I am eager to see for how long I can keep this habit going :)