OCI manager Apps (beta) — official container images as native LXC

[MacRimi]

Hi everyone,

This is the thread for OCI manager Apps, the new section in the ProxMenux menu, so the conversation about it lives in one place. I'll post here when its text has settled and is ready for a translation pass, and close the thread once those changes are in. Before that, there's something I could really use a hand with.

What it is
A new entry in the main menu that installs applications from their official container images as native Proxmox LXC. There is no Docker engine anywhere: ProxMenux reads the published recipe of each application and turns it into a container Proxmox runs itself, with its own address on your network, listed in the Proxmox interface like any other LXC and covered by the same backup jobs.

How it was built
More than three hundred Docker Compose files — from LinuxServer.io, other public Docker image repositories and recipes written for ProxMenux — have been translated into the format Proxmox understands. The whole point of that translation is that nothing is lost on the way: the volumes, the environment, the ports, the devices and the first-run behaviour are the ones the image's author published, so using an application here should be no different from using it under Docker. Applications made of several images are installed as several LXC, wired through a private bridge of their own.

Images that aren't in the catalogue can be installed too, by pasting their Compose file, a docker run line, or just the image reference.

Where it stands
It's in develop, under testing. Every recipe in the catalogue has been reviewed by hand. What I have not been able to do is install all of them — there are 350, and a good number need hardware, an account or a service I don't have here.

It also brings around 1,600 new strings, which is why I'm not asking for a translation pass yet: the wording is still moving and I don't want anyone translating the same screen twice.

Testers wanted
The most useful thing you can try is an application you already run under Docker, because you're the only one who can tell whether it behaves the same way. Whether it starts is the easy part; whether it works is what I can't check on my own.

If you hit a problem
Open a new reply with:

The application, and the image if you changed it.
The configuration you chose — default or advanced install, container volume or host directory for each path, DHCP or a static address, GPU if you passed one through.
The error from the terminal, copied as it appeared.
Every installation also writes a log to /var/log/proxmenux/oci/<application>-<date>.log. If the terminal has already scrolled past the problem, the tail of that file is usually the fastest way to see what happened.

The configuration matters as much as the error. The same application can install cleanly one way and fail another, and without knowing which path you took I'd be guessing at where it broke.

And if nothing breaks
Problems that don't announce themselves are worth just as much. If a screen reads badly, if you weren't sure what a question was asking, or if an application installed cleanly and then turned out to need something the summary never mentioned — say so here. That kind of thing never arrives as an error, and it's only visible to someone going through the flow for the first time.

Thank you — genuinely. This is the part of the work I can't do alone.

[MacRimi]

Update — it's merged.

The OCI manager is in develop now. Since this thread opened, the part worth reporting isn't the engine but the text: every application's description goes through the same translation path as the rest of ProxMenux, so the catalogue reads in all eight languages instead of only English. That was two separate systems until this week, and it was the reason a translation pass would have been wasted work.

The catalogue stands at 365 applications. Fail2Ban came out — it is built around the LinuxServer.io container's own configuration layout and doesn't survive the move to a native LXC, which is the honest reason rather than a temporary one.

What hasn't changed is the ask. I still haven't installed most of these. The catalogue is reviewed by hand, and reviewing a recipe is not the same as running it. If you already run something on this list under Docker, that comparison is the one thing I can't do from here.

The wording is closer to settled than it was, but I'd still hold off on a translation pass. I'll say so here when it's ready.

[f3rs3n]

I’m keeping the curated Italian delivery on hold as requested. While checking the landed OCI code, I found a small group of diagnostics and recovery messages that overstate what the code establishes. I have a local wording-only patch with offline regression tests, leaving operational behavior unchanged. Would that be useful to review now, or would you prefer I wait for your wording pass?

[MacRimi]

Hi Martino, how are you?

Something lovely happened today that I'd like to share with you: Vaso73 has offered to help test OCI Manager for real, and we've started organising it in #392. If you have a moment, I'd love for you to read that conversation.

It connects directly with what I asked for when this thread opened. There are more than 360 applications in the catalog, and I can't run most of them myself. Anyone who tries an application and finds that its image needs improving, needs fixing, or simply doesn't work as a native LXC is giving us exactly the information we're missing. It doesn't have to be a full report: telling us which application, what you saw and how to reproduce it is already a great help.

If you feel like joining in, the idea would be for each of you to take different applications, whichever you already know or run, so nobody repeats the same work and the catalog gets covered faster.

What do you think? Would something like this fit with what you're already working on, or would you rather approach it differently?

[f3rs3n]

Hi MacRimi, thanks for the invitation — I’ve read #392, and Vaso’s PocketBase and Glances comparisons are a useful model.

I’d like to finish the Italian translation and the source fixes blocking it before taking on application testing, so I can bring that work to a proper close first.

After that, I’d be happy to test some Docker applications I already know. I’ll coordinate the selection here before starting, so we cover different workloads rather than duplicate Vaso’s work.

[MacRimi]

Hi Martino,

Wait a day, and then it's worth looking at.

There's a PR going up tomorrow with several changes, and a good part of it is text. The catalogue's 28 category labels are rewritten by hand in all seven languages, with one conjunction per language instead of a mixture of two, and the product names left alone — OCI manager Apps, the Arr suite, IoT, NVR, VPN and ERP are not translated into anything now. The App tab also gains its own wording for containers installed from an image. Rebasing your patch on that will be less work than reconciling the two afterwards.

Your reading of those diagnostics is the part I'd like to see. A message that claims more than the code can establish is the kind of thing that only shows up when someone reads the code and the string side by side, and the OCI recovery paths are exactly where that matters: somebody reads them when an operation has already gone wrong.

One thing that may change how you plan the Italian delivery: the translation builds no longer write over a translation that already exists. All three of them — the menu catalogue, the Monitor messages and the documentation — only fill what is empty, and an overwrite now has to name the strings it is allowed to touch. Curated wording stays put from here on.

Thanks for holding it while the wording moved.

[Vaso73]

Hi @MacRimi and @f3rs3n,

As OCI catalog validation grows, would it be useful to use the existing ProxMenux Roadmap as the shared overview for this work?

I am thinking of a small OCI validation lane or filtered view, rather than a new project or an issue for every catalog entry:

• Ready to pick — an untested app or a small, similar batch that anyone can choose when they have suitable time and hardware.
• In progress — only while somebody is actively testing it, to avoid two people doing the same work at once.
• Done, Review, or Blocked — the objective result, linked to the relevant reply in this thread, PR, or reproducible issue.

The point would be a self-service queue, not permanent ownership: a contributor could simply look at what is still open and pick something that fits their environment. The roadmap would only make the current coverage easy to see; the detailed configuration and test result would stay in this thread, where you asked for OCI conversation to live.

For clarity, a completed item would name the exact tested scenario rather than claim that every possible configuration of an app is covered. For example, default or advanced install, volume or host directory, DHCP or static address, and any GPU choice would remain part of the linked report.

Would that fit the way you would like OCI testing to be coordinated? I would of course follow your preferred naming and workflow.

@f3rs3n, there is no need to act on this before your Italian work is complete; I thought the shared view could simply make it easier for us to choose different applications when you are ready.

[f3rs3n]

Hi @Vaso73, I think this is an excellent approach. Reusing the existing roadmap as a lightweight, self-service queue would make coverage visible and help us avoid duplicate work, without creating permanent ownership or an issue for every application.

I especially like keeping “done” tied to the exact scenario tested, with the configuration and results here in the discussion rather than treating one successful test as validation of every configuration.

Thanks also for keeping my Italian work in mind. Once the translation and its blocking fixes are finished, I’d be happy to pick applications this way, following whatever workflow MacRimi prefers.

[MacRimi]

Hi @Vaso73 and @f3rs3n,

First of all, thank you both. What you're putting into ProxMenux is going to mean a leap in quality, improvements and functionality that I couldn't reach on my own, and I'm really grateful for it.

I've been thinking for a few days about how we could organise this better between us, because until now the project has never had active collaborators like you. I've also been thinking about how to handle the validation of the OCI images so it's as useful and practical as possible. My first idea was this discussion thread, but it didn't quite convince me: reports get buried as the thread grows. Then I thought about adapting the README in the oci folder so validated images could be marked there. I liked that, but I wasn't sure how to do it or how to link it so it would be visible to anyone who wants to help. Your idea of using the board is fantastic, and I think everything can fit together like this:

The board is the queue. It shows who is testing what right now. A card is created when someone picks an application or a small batch, so it never fills up with the whole catalog at once. I'd add a Blocked status for cards that can't move forward for reasons outside the tester's hands: hardware nobody has, an image that needs something only Docker provides, or a fix still pending in ProxMenux. That way they don't sit in "In progress" looking active, and nobody picks them up again to repeat the same failing test.

Each test gets a short report form. It would be an issue form with fixed fields: application, version, default or advanced install, volume or host directory, DHCP or static address, GPU, result, and how to reproduce it. Every report then describes the exact scenario tested, as you both suggested. The form adds itself to the board, so anyone can take part, not only people with board access.

Validation is recorded in the catalog. Once a report is reviewed and labelled, a bot adds the entry to oci/catalog/verification.json with the tester's GitHub user, the date and a link to the report. From then on, the OCI installer shows the application as verified, with the ✓ mark in the lists. Anyone who prefers a PR can still add the entry directly.

A generated oci/VALIDATION.md, linked from the README. It lists every validated application with who tested it, when, and a link to the report, and explains how to join in, so anyone can see what's still open without us maintaining a list by hand.

This thread stays for the conversation: questions, ideas and coordination.

Apart from that, I'm giving you both write access to the whole board. You'll be able to move cards and create new ones for any idea that occurs to you, and develop it yourselves from start to finish.

What do you think? Does this fit the way you'd like to work, or would you change something before I set it up? And Martino, there's no rush at all. Finishing the Italian work first sounds perfect to me.

[Vaso73]

Hi @MacRimi,

This sounds wonderful. You have taken the loose ideas we were discussing and turned them into a really clear and practical way of working together.

I especially like that the board stays simple and only gets a card when somebody actually picks an application or a small batch. That should make it easy to see what is happening without filling it with hundreds of entries no one is working on yet.

The short report form, the catalog record, and the generated validation page all fit together very naturally too. It gives each test a useful home, makes the results easy to find later, and gives new contributors a clear way to join in.

The Blocked status is a very good addition too. It makes a genuine limitation visible instead of leaving an item looking active forever, and should save the next person from repeating the same dead end. When you come to shape that part, it may also be helpful if a blocked report says briefly why it is blocked and what would make it worth trying again.

The model fits very well. One other small thought for whenever you design the verification record: alongside the tester, date, and report link, it could be useful to keep the exact image digest and a short description of the tested scenario. That would make it easier to see when an image has changed and an older verification should simply be treated as stale rather than as a current guarantee.

Thank you as well for offering board access. There is no rush from my side — once you have the shape of it in place, I would be happy to review the flow carefully and follow it for the next validation.

And @f3rs3n, I am looking forward to comparing notes once your Italian work is comfortably finished. I think this will make it easy for us to cover different workloads without stepping on each other’s work.

[MacRimi]

Hi @Vaso73 and @f3rs3n,

Right, let's see if this contraption actually flies.

It's in place now. You both have write access to the ProxMenux Roadmap, and the whole flow is described in oci/VALIDATION.md. In short:

Picking an application. Create a card for it on the board and move it to In progress while you test it. Anything not listed in VALIDATION.md is open.
Reporting. There's an OCI validation report issue form with the application, image version and digest, Proxmox version, install mode, storage, network, GPU and result. The digest is the one the Monitor shows in the App tab of the container, for example 2026-09-06 · b1f339cf. The form adds itself to the board.
Validating. A reviewer reads the report and comments /validated. A bot then records it in oci/catalog/verification.json with the tester's user, the date, the image digest, a one-line scenario built from the form, and the link to the report. It regenerates VALIDATION.md and closes the issue, and from then on the installer shows the application as verified. You're both in the reviewer list, and nobody validates their own report, so every validation gets a second pair of eyes.
Blocked. A card that can't move forward goes to Blocked, with a line saying why and what would make it worth trying again.
Vaso, both of your ideas made it in: every validation now records the image digest and the scenario, so a newer image reads as not yet tested rather than as covered, and blocked cards carry their reason.

One practical detail: GitHub only enables issue forms and issue-triggered bots from the default branch, so the form and the bot become active with the next release to main. Until then, a validation can be added with a pull request to verification.json (VALIDATION.md explains how, and CI checks it), or posted here with the same fields.

Thank you both again. And Martino, still no rush at all.