Bundle Ficsit for modding

[Genda1ph]

Sorta depends on #478, but should be rebaseable.

• Add a --build-arg FICSIT='true', that, when set, installs latest version of ficsit CLI from the official repo.
• Update run.sh to check if ficsit is installed and profiles.json is available.
• Update README.md.

[wolveix]

Hey @Genda1ph. I closed your other PR, so this should probably be rebased.

Your $HOME comment is not a bug. The image uses root for reasons covered in the README and elsewhere.

I'm not sure what benefit there is to including FICSIT in this image to be honest. Per previous discussions around modding support, the intention here is to be as hands-off as possible. Not to mention, this is currently architected as a build argument which seems like an odd implementation. If it were to be included, it should either always be included, or have a set image tag that people could use. Needing to build the image itself means very, very few people would actually use it.

Additionally, if anything it should check the latest version available during runtime. Otherwise, if I don't push a new image for a while, people may complain that FICSIT is out-of-date. I'm very hesitant to include any unnecessary dependencies for exactly this reason :)

I've been away from FICSIT for a little while; would you mind covering what benefits this provides over the current approach?

Thanks so much!

[Genda1ph]

Thank you for taking time to answer a random PR. My other PRs seldom get a good response 😩

Per previous discussions around modding support, the intention here is to be as hands-off as possible. Not to mention, this is currently architected as a build argument which seems like an odd implementation.

It's fairly common for me to rebuild and customize images, and this was intended as experimental, hence the build-arg route. I also don't think that ficsit would cause any old version issues - it downloads the versions specified in the profile from the site, so until there's a major change, which breaks backwards compatibility - it should be fine.

As a side note: I went and rebuilt my local image to Ubuntu 26 (running on Debian Trixie), and it's a drop-in upgrade to the previous one, so the test sample is rather small, but it works.

Your $HOME comment is not a bug. The image uses root for reasons covered in the README and elsewhere.

There is nothing wrong with running image as root, then dropping privileges. The problem is that under normal operation, run.sh is ran as steam, but $HOME resolves to /root, instead of /home/steam, which isn't ideal.

I've been away from FICSIT for a little while; would you mind covering what benefits this provides over the current approach?

First and foremost, ficsit CLI is recommended on the documentation referenced in the modding section.

Essentially, ficsit CLI is the text-based equivalent of SMM: you can export a profile from SMM and feed it directly to ficsit, provide installations.json, then run ficsit apply - it will download and install all the mods for this profile, which greatly simplifies server modding.

While I generally stick to atomic images, this PR can be reworked and extended to:

• Install ficsit on (re)start.
• Download profiles.json via curl.
• Auto-generate installations.json.
• Support different profiles.

Let me know which route you'd prefer to go, but there's a decent chance I'll end up maintaining a fork anyway.

[wolveix]

For sure, Ubuntu 26 would work just fine in my environment too. The issue is that a lot of users of this repo are in unusual or specialized environments which can and do break with these kinds of updates, particularly NAS-adjacent environments.

Regarding $HOME, for sure, I believe that's down to how we call run.sh from init.sh. If you followed the README to build the image as non-root, I presume it would resolve it.

Yeah sorry, what I meant when asking about FICSIT was understanding why it's advantageous to be included in the image. I'm still not seeing why it's really any easier than just running the CLI outside of the Docker image.

Yeah I figured that's why you left it as a build argument. Likewise, I generally prefer to keep images atomic and single-purposed; it's why I'm always hesitant to introduce new functionality to the image, especially if it's not something I'll be using a lot myself (meaning if things break, or people run into issues and they will run into issues, I'll have to figure them out).

[Genda1ph]

Yeah sorry, what I meant when asking about FICSIT was understanding why it's advantageous to be included in the image. I'm still not seeing why it's really any easier than just running the CLI outside of the Docker image.

This adds almost rudimentary support for ficsit. If we extend it a little (generate installations.json and add profile support via env), we could allow people to install mods by simply providing 2 things:

• profiles.json with a mod list, either from running the tool locally or from SMM.
• Setting a few environment variables.

This, I think, is much more convenient than attaching an SFTP... Which would still be an option to provide the profiles.json file.
Just having an ~8 megabyte binary in the image doesn't significantly increase maintenance burden.

[wolveix]

I don't know how much experience you have maintaining repos, but introducing any additional dependency does increase the maintenance burden. What if their repo path changes? What if they have breaking changes, either to their release pipeline or usability of the tool? What if they have a critical vulnerability? What about edge-cases (e.g. issues being opened asking for us to support X feature of CLI)? What if the tool becomes unmaintained? What if someone wants an alternate mod manager for Satisfactory in the future, do we support both?

To be clear, I think the inclusion is probably a good idea. The current structure was agreed upon after discussing with the FICSIT maintainers themselves and the community when modding support was first added to dedicated servers. You don't have to use SFTP to use modding with this image. There is nothing stopping a user from running the FICSIT CLI next to the image, and it would work just the same (I believe many people already do this, from past discussions).

The two main things giving me pause are the above maintenance concerns, and that no one has requested this functionality. Would it be useful to have? Maybe :)

[Genda1ph]

I haven't requested it because I've added it for myself, and then raised this PR 🤷 I also haven't maintained any public/FOSS projects, but I do maintain internal tools for a living.

After giving it a bit more thought, the simplest and maximum hands-off method for adding this would be to:

• Set ENV FICSIT='false' in Dockerfile. Add a check to either init.sh or run.sh.
• When set to true, we have two options:
  • Go and download the binary, generate installations.json, but don't try to do anything else if there's no profiles.json.
  • Or do nothing at all if there's no profiles.json.
  • Liberally use environment variables with defaults in the flow, in case something changes. Add them to documentation.
• Throw warnings when things are misconfigured, for easier troubleshooting.
• Once we have FICSIT='true' and profiles.json is found - apply mods from profile FICSIT_PROFILE=${FICSIT_PROFILE:-Default} to the install.
  • Do we need to make this reversible? If mods are installed, but now FICSIT='false', should we just error out or what?
  • We could check FICSIT_DISABLE, and if that is true, then remove the mods managed via ficsit?
  • What to do if FactoryGame/Mods/ is not empty? This happens when there are mods installed manually. I would assume - crash before corrupting data and let user deal with it?
• Finally, run the server.

All of the above is fairly easy, but I'm not 100% sure about mod rollback. installations set-vanilla and then apply should completely remove FactoryGame/Mods, but I would keep some safeguards in place.

On using init.sh vs run.sh:

• init.sh has access to /usr/local/bin and /opt, but running as root is less secure, as sandbox escapes are much easier.
• run.sh runs as user, but we can still save ficsit under something like ~/.local/bin/ or /config/bin/ and beat it into submission via CLI flags.

I have no preference here.

[wolveix]

I like the direction you're heading in! I think gating it behind an environment variable and profiles.json is probably a good idea. Regarding reversing it, that's an interesting point...I'd probably just log a warning and let it continue.

I'd probably run it under run.sh unless there's a reason to use init.sh for it. I appreciate you working through a few different options, and hopefully we can agree on a path forward together! 🤩

[Genda1ph]

Nuked the branch and rebuilt from scratch based on previous discussion.
This is more of a preview: I still need to add a rollback procedure and test everything.

Let me know if the direction looks good and if I need to change anything before I invest more time into this.