After reading the documentation page at https://fossil-scm.org/home/doc/trunk/www/tech_overview.wiki, I still am not 100% sure about how to set up Fossil to run via CGI scripts. I have access to a shared hosting platform which has CGI enabled. I can run Perl, Python, and shell scripts via CGI, but nothing written in any other language. I tried to log into my server using ssh, but this was not allowed due to the shared hosting of my account.

Since I have various other domains running under my top-level domain, I need to get this right before I do something stupid which might impact those sites. So far, I have only used PHP and one MySQL schema as well as serving static HTML content.

This is what I have understood so far (it's a server running Linux and Apache, BTW). Most of the following questions I have concern file permissions, but I want to know if the steps I am describing are correct?

1. In the folder hierarchy of my shared hosting platform, I need to create a folder one level above the "public_html" folder, e.g. a "bin" folder where I put the Fossil executable. I need to set the executable flag in the permissions. I assume 755 is appropriate here for both the folder and the Fossil executable?

2. As a sibling to the "bin" folder, I need to create a folder to hold the repository (or repositories), e.g. "repo", permissions 755. I copy an existing repository database to this folder. It is recommended to be named with the extension ".fossil". Should permissions of 644 be set? Or should they be stricter?

3. Do I need to copy only the repository to the server, or the source tree as well? From what I have read, it seems that only the repository is necessary.

4. For each repository, I create a CGI script similar to this (which will be an executable file with extension ".pl" or ".cgi" and uploaded to the server's "cgi-bin" location):

    #!/home/XXX/bin/fossil
    repository: /home/XXX/repo/myproject.fossil

Afterwards, I should be able to access the Fossil repository on my server with a URL conforming to the server's naming convention.

Another question: Fossil creates a configuration database named "~/.fossil" (or "~/.config/fossil.db" on my local machine). Does the server instance of Fossil create this as well, and if so, where is it located? Do I also need to create a ".config" subdirectory under my "/home" folder on the server for Fossil to use?

I assume that the next step would be to read up on how to prevent abuse of the Fossil setup from spam. Ideally, at least at first, this will be "taken private" and force users to access the site using their login credentials.

Thank you for helping this newbie!

... I need to create a folder one level above the "public_html" folder, e.g. a "bin" folder where I put the Fossil executable. I need to set the executable flag in the permissions. I assume 755 is appropriate here for both the folder and the Fossil executable?

Correct, but depending on how the hoster runs CGI platforms, even 0500 might be sufficient. Most hosters, in my experience, run CGIs under the user whose account they're running in.

However, since you cannot ssh to your hoster and build a fossil binary directly on that system, you will probably need to build a static fossil binary to upload to your hoster so that it will be independent of any system-level libraries they have (or don't have), or breakage caused by system-level updates.

Presumably your hoster is a 64-bit Linux system, in which case building such a binary is trivial once you've gotten past the voodoo of setting it up: This document does into a great deal of detail about how to use OCI containers (like docker) to build static binaries. (FWIW, that's how i build fossil for my server.)

As a sibling to the "bin" folder, I need to create a folder to hold the repository (or repositories), e.g. "repo", permissions 755. I copy an existing repository database to this folder. It is recommended to be named with the extension ".fossil". Should permissions of 644 be set? Or should they be stricter?

0644 is fine but 0600 will likely also work fine for you. It's important that the directory which contains your .fossil files is writeable by your account (so 0755, or even 0700).

Do I need to copy only the repository to the server, or the source tree as well? From what I have read, it seems that only the repository is necessary.

Only the repository. Make sure to set up your admin user account on the repository before copying it to the server. This can be done via "fossil ui" or the "fossil user" CLI command.

For each repository, I create a CGI script similar to this (which will be an executable file with extension ".pl" or ".cgi" and uploaded to the server's "cgi-bin" location):

Exactly. Your best bet is to first try .cgi. Whether or not the .cgi extension is actually required is dependent on the hoster's configuration.

Afterwards, I should be able to access the Fossil repository on my server with a URL conforming to the server's naming convention.

fossil clone https://YOUR_ADMIN_NAME@your-domain/cgi-bin/your-fossil-repo.cgi my-fossil-repo.fossil

Another question: Fossil creates a configuration database named "~/.fossil" (or "~/.config/fossil.db" on my local machine). Does the server instance of Fossil create this as well, and if so, where is it located? Do I also need to create a ".config" subdirectory under my "/home" folder on the server for Fossil to use?

Fossil will create it as needed but IIRC it won't create one for such a hosting case because repos served that way do not modify the global configuration. IIRC. You shouldn't need to concern yourself with that file at all (FWIW, i don't on my server).

I assume that the next step would be to read up on how to prevent abuse of the Fossil setup from spam. Ideally, at least at first, this will be "taken private" and force users to access the site using their login credentials.

It can't hurt to do so but in practice is not usually necessary. There's certainly nothing wrong with the "take it private" approach, especially if you have reservations about fossil's security. To the best of our knowledge, there has never been an remote exploit against fossil which did not itself require credentials for a trusted user (knock on wood). However, if a repository's permissions are set up too lax, it is possible for spam bots to edit fossil wiki pages and tickets (we've definitely seen that happen).

Thank you, Stephan. This was very helpful!

Question about building Fossil as a static build:

According to the "build.wiki" page, I can just add "--static" to the ./configure command?

Why is this "more difficult" than downloading and installing Docker, then following the instructions for using that?

According to the "build.wiki" page, I can just add "--static" to the ./configure command?

Kinda. That won't build a completely static binary on most Linux platforms because GNU libc cannot statically link the networking libraries. It will create a static binary which still requires dynamic linking to those and it requires the same version as was used during the build process. So it's "mostly static" but not truly static. It might or might not work on your hoster, depending on exactly which version of glibc they're running. Even if it works today, an OS upgrade on their part in the wee hours of tomorrow morning might break your fossil "static" binary.

The docker build uses Alpine Linux, which uses a different libc which is capable of producing genuinely static binaries.

Ok, I've been looking at the Docker website:

"(Requirements): Have a 64-bit version of either Ubuntu Jammy Jellyfish 22.04 (LTS) or Ubuntu Impish Indri 21.10."

I'm on Ubuntu 18.04 LTS for now, so this is a no-go for me unless I update my system (which I have no other reason to do than building Fossil).

Looking at all of the threads about static vs. dynamic linking, it seems mostly about linking against libc. My web host uses PHP 7.4 and I have 7.2 on my local system; however, I have iconv version 2.27, and the host has 2.23 (also the glibc implementation).

Both of these link to the same shared libc on my system, so I will take my chances doing a --static build of Fossil without Docker (which, as I already said, I cannot use). I think things are close enough that it might just work OK.

For the moment, it isn't essential that it works, but it would be nice if it does. I just don't want to crash my host server by running Fossil! :)

I will take my chances doing a --static build of Fossil ...

On second thought, there are several warnings which appear when building statically with the current Fossil sources.

It is likely safer just to use the pre-compiled binary image of Fossil downloaded for Linux 64-bit than to go the static route (unless you can use Docker, that is).

Ubuntu 18.04 LTS…update my system…no other reason to do than building Fossil…

A better reason to upgrade is that that version is nearly out of support. You've only got about a month of security and critical bug fix updates left.

That said, Canonical's got your back: there's a docker.io package in the 18.04 LTS repo that seems to work:

$ sudo apt install docker.io
$ sudo usermod -aG docker $USER
$ sudo reboot                     # …or just log out and back in
$ cd ~/src/fossil/trunk
$ docker build -t fossil .

…and so forth from the static container build instructions. I tested it here, and it does work.

At some point the bionic package repo will be archived, so you might want to install it now even if you are going to take another path, if only so you don't have to go chasing the APT sources around.

My web host uses PHP 7.4 and I have 7.2

If you install a VM of the same OS your web host uses, you can build dynamically and upload the executable as-is. The libraries will be compatible, allowing you to avoid all this mess.

safer just to use the pre-compiled binary image of Fossil

🤷‍♂️ I'm the primary maintainer of the Docker build system for Fossil, not drh, and I can kinda understand why you might drop me a notch or two down the "trust" list, but ya gotta ask: how long do you think I could get away with providing bad container build code via the official Fossil repo?

A better reason to build your own binaries than any distrust you might have in drh or I is that you want a different feature set than what we provide. Both the official Fossil binaries and those you get from my stock container build instructions have the default feature set. If you want something nonstandard, you'll have to build it yourself.

That said, Canonical's got your back: there's a docker.io package in the 18.04 LTS repo that seems to work:

Thank you, Warren ... this is fantastic news!

docker.io

I had seen that package in the repo lists, but wasn't sure that it was what I needed.

I installed docker, but building fails on my system:

COPY containers/os-release /etc/os-release

COPY failed: file not found in build context or excluded by .dockerignore: stat containers/os-release: file does not exist

Where do I get that file? Do I need to run "sudo docker..."?

Success at last! :) I can run the resulting binary now on my local machine. Haven't tested it yet on the web host, but I am confident it will work.

Thanks for your patience, Stephan and Warren.

As a small suggestion, it might be a good idea to include a short sentence in the build instructions to the effect that when building with Docker, it is still necessary to run ./configure BEFORE continuing with running Docker.

It wasn't obvious (to me, at least).

Normally building a container is one of the last things you do, after you've tested things locally with a regular build, since it's a faster build-test-change-retry cycle that way.

If you're of a mind to skip steps, you should just go pull one of my existing containers and not build locally at all.

(You still need Docker Engine for that, or something sufficiently close in functionality.)

That paragraph was wholly outdated. If you reload it, you'll get all the "why" you could care for. :)

Thanks, Warren.

I think you meant this? :)

https://stackoverflow.com/questions/3430400/linux-static-linking-is-dead

Indeed, I must have been looking at a stale version of that page.

Indeed, I must have been looking at a stale version of that page.

You were - he updated that page in response to your post ;).