Compose files templating improvements

[tgaugry]

This PR add a few things related to compose file templating (see #19).
This adds :

• A way to have common values for all stacks, instead of specifying the same variable over and over in each stack values_file. These can be specified either in the "global_values" field in config.yaml, or in a file named global.yaml (same behavior as the "stacks" variable. They can be overriden in stack values_file, if needs be.

• You can now use sprig functions in compose.

• You can use go templates defined in the "template" folder.

• The web UI now shows original and generated files (if available)

[tgaugry]

@m-adawi @sanzoghenzo Hey guys, is there anything I can do to make this progress forward ? Like, a companion PR on swarm-cd-example or something like that ?

[sanzoghenzo]

Hi @tgaugry, sorry for the delay!

I still have to finish the review, but I kindly ask you to add a documentation of the new features in the readme file, so that I can better understand the choices you made in your edits.

[sanzoghenzo]

OK, I think I understand your changes.

I don't use the WEB UI, so to me it is a bit much having to manage a "cache" directory (doesn't seem like a cache since it is recreated at each update without checking if anything changed - but that's just semantic and I get what you wanted to do 😉 ) and perform I/O operations just to be able to download the rendered compose file.

I'll leave to @m-adawi to decide, but couldn't this be turned into an on-demand API?

[tgaugry]

TBH, I don't use the web ui much either, but I think having a way to debug and compare template vs generated file is necessary.

I agree that recreating everything each time is a bit silly - other than the disk io, it also hit registries which is a bit annoying. I wanted to also do a PR about that, but I just couldn't find the time.

To me there is 3 alternatives:

• Going back to previous code - it just modify in place the compose file (so that swarm can read it). If someone wants to see the source template, they pull their git. Problem is that people will have no way to check what was generated.
• Tying it down to a debug flag
• Generating it on demand in the UI - Seems like the best option, but it seem quite a big dev since I'm not sure it's possible to do without merging the parts in folder swarm-cd and web.

To me the most feasible option is 2 - that way files can be checked either in the UI, or by mounting a volume.

Any opinion @sanzoghenzo ?

[sanzoghenzo]

* Going back to previous code ... Problem is that people will have no way to check what was generated.

I agree, the output it useful when testing out new templates!

* Tying it down to a debug flag

This would be a good compromise to have this PR merged quickly

* Generating it on demand in the UI - Seems like the best option, but it seem quite a big dev since I'm not sure it's possible to do without merging the parts in folder swarm-cd and web.

No need to merge parts, just add a route for GET /stacks/<name>/compose or something similar, a controller function that gets the name from the url and calls a swarmcd function that builds and return the byte stream like it now does in updateStack.

This can also be used without the web UI (via curl or any other HTTP client with access to swarmCD web server) and there will be no need to poke into docker storage.

I'm fine with either solution, maybe we can do 2 and when you (or anyone else that wants to contribute) have more time you can try 3?

[sanzoghenzo]

• Problem is that people will have no way to check what was generated

I was thinking about this just today, I would like to test a templated stack locally without the need to spin up a swarmCD instance...
It would be great to have a cli tool that does only that!
This would mean extracting the core logic to a separate module that can then be called by both swarmcd and the tool (that could be a sub-command of the current program if a separate program is overkill).

I'm not saying that you need to do that 😅 , it's just a thought... I'll make this into an issue ASAP!

[tgaugry]

I tinkered a bit yesterday, and you were right, solution 3 is not that complex - I was tricked by the function export rules from go (starting with an upper case letter vs not).

This would mean extracting the core logic to a separate module that can then be called by both swarmcd and the tool (that could be a sub-command of the current program if a separate program is overkill).

Honestly, with solution 3 I feel like a good chunk of the work is done for that. I'll go that route, and I'll see if I can find the time for #127

[tgaugry]

That should do the trick:

• Getting files in the UI is now on demand.
• Added documentation about templates and variables
• Made the template parsing more lenient; if it cannot load templates, try anyway.
• Added the template-gen exec for Tool to check the result of a templated stack #127

Current code is running on my setup, this is what I get in the UI:

This is what you get when you have a bad template (intentionally removed "}}"):

$ docker run -e LOG_LEVEL=debug -v $(pwd)/testdata:/data --rm -it swarm-cd:latest /app/template-gen --global /data/globals.yaml --valuefile /data/values.yml --templatefolder /data/template /data/compose_notemplate.yml
time=2025-10-26T12:32:36.435Z level=DEBUG msg="reading stack file..." stack="Template test" branch=nobranch
time=2025-10-26T12:32:36.435Z level=DEBUG msg="rendering template..." stack="Template test" branch=nobranch
time=2025-10-26T12:32:36.435Z level=DEBUG msg="Loading template folder..." stack="Template test" branch=nobranch
time=2025-10-26T12:32:36.435Z level=ERROR msg="Could not parse templates, trying to generate stack without them." stack="Template test" branch=nobranch error="template: volumes.tmpl:3: unexpected \"{\" in define clause"
---
version: '3.8'
services:
  traefik:
    image: traefik:v3.5
    [SNIP]

[sanzoghenzo]

Looks good to me! I still didn't test it, though.

@m-adawi have you any thought about this PR? should I proceed with the merge or do you want to try it first?

[tgaugry]

Great, thanks for your time @sanzoghenzo !

For what it's worth, this is what I run currently in my homelab - haven't seen any weird behavior. Still, a second test would be nice.