Advice for packaging a web app

Hello !

I would like to package this application: https://www.dolibarr.org/. (Issue)

It is basically a PHP application that needs to be served with a webserver and PHP.

I want to be sure that my approach is correct.
First, I was planning on adding both a package (pkgs/servers/dolibarr/default.nix) and a NixOS module (nixos/modules/services/web-apps/dolibarr.nix) that would expose options services.dolibarr.*.

I am following the official instructions:
Manual installation.

Basically:

  • Configure a database for dolibarr (I see how to do this, and what options to expose).
  • Get the sources and decompress them.
  • Create a conf.php configuration file.
  • Configure a webserver that should serve the dolibarr folder
  • Configure a PHPfpm pool

My main concern is the following:
“Where” should live the “dolibarr” folder. As it is the “result” of the fetchFromGitHub of the dolibarr package, it would basically be in the /nix/store.
However, when it comes to configuring the service, it should be writeable by the web server.

At first, I thought about splitting it in an “immutable” part that would live in the /nix/store and a “mutable” part that would live for instance in a configurable location (that could be /var/lib/dolibarr by default).
This is what the nextcloud service is doing.
The problem is that it is not really possible to split it like this.

I would be glad to have advice about how I should do this.

That’s how a well written web server should behave. If you can, consider rewriting it to behave this way; mixing code and data is almost always a bad idea.

Sometimes we can’t choose the best tools. In these kinds of cases, you could write a script that copies all the contents from /nix/store to /var/lib before the server runs, and then just launches the application from /var/lib.

The problems you run into are that it’s hard to delete files that have been removed from the web server (because they’ll stick around as data), and that you might accidentally overwrite data, or other things like that.

Less simply, you could look into setting up an overlayfs, or using a nixos container.

Either way, this application isn’t making your life easy, consider if you could rewrite it to behave (changes should hopefully not be too involved, but you never know with PHP), or use a better one, you’ll be much happier.

1 Like

Does anything need to be writable after you run through the install wizard?

1 Like

Thank you for your help !

I read a little bit more and made it work on my NixOS server (without writing a derivation: I just extracted the archive manually and created the folders myself).

Here are some more information.

So, there are basically two folders involved.

  • One containing the actual software: /var/www/dolibarr/ by default. It is not suppose to change after the installation (see below). It is what the webserver is serving.
  • One containing the mutable data: /var/lib/dolibarr/documents by default. Its content has to be writeable.

The problem is that there is an ‘installation step’ that happens in the browser the first time (by navigating to https://my_dolibarr_domain.example.com/install).
So this setup cannot happen in the derivation process.
This step asks the user for some detail (domain/url, database access…), creates the database if needed and populates it.

After this, only the documents folder can change.

I looked at their manual, looks like that’s the only documented way indeed. It’s annoying, that stuff should really be part of the configuration data (and likely is in practice, it’s just not separated from the code - can’t blame them, PHP naturally makes you do this kind of thing).

I’m sure they have a way to do that setup without having to go through the website though. It would be incredibly cumbersome to test or deploy this at scale if you had to go through the setup every time.

You have a few alternatives:

  • Check their rpm package to see if it does something to separate code from config; it should have some mechanism for this in theory.
  • Check upstream (mailing list or whatever) to see if they have a script that does the setup from the CLI instead of a browser or such.
  • Check what files actually change after you complete the setup, copy them out and keep them as a tarball to install in the derivation.
  • Write a script that does the configuration for you on the files, based on the differences you see and some guesswork.
  • Write a script that does the config using curl.
  • Give up and do what you do now.

The config really should be separate from the code, because without that separation it’s impossible to write a generic immutable package…

1 Like

Thank you TLATER for those precisions.

I just encountered an ongoing pull request for this package.
I will have a look at it later.

In case someone is interested: https://github.com/NixOS/nixpkgs/pull/185258.

@glepage I went ahead and packaged this: Comparing NixOS:master...aanderse:nixos/dolibarr · NixOS/nixpkgs · GitHub

My intention was to provide this code as an example of how to package a php application for NixOS. I have no intention of using this software so I won’t be maintaining the code or creating a PR - anyone interested in doing so should feel free to take the code and run with it. I would be happy to answer any questions or help out a little if needed.

Hosted by Flying Circus.