feat: add documentation for diracx container deploment by marianne013 · Pull Request #851 · DIRACGrid/diracx

marianne013 · 2026-03-24T13:39:04Z

This attempts to address #798.

read-the-docs-community · 2026-03-24T13:41:02Z

Documentation build overview

📚 diracx | 🛠️ Build #32291009 | 📁 Comparing 848aa17 against latest (4c7853a)

🔍 Preview build

150 files changed · + 4 added · ± 146 modified

+ Added

± Modified

fstagni · 2026-03-24T16:08:23Z

-At the time of writing, the only supported way of running DiracX is through **[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/)**.
+At the time of writing, the only fully supported way of running DiracX is through **[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/)**.
+
+If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. This has only been tested in conjunction with a DIRAC v9.0 deployment. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).


Given that now you are introducing a new "path" of deployment, the whole content of this file should be, I believe, better moved one level up, from https://diracx--851.org.readthedocs.build/en/851/admin/how-to/install/minimal-requirements/ to https://diracx--851.org.readthedocs.build/en/851/admin/how-to/install/

chrisburr · 2026-03-27T07:31:34Z

-At the time of writing, the only supported way of running DiracX is through **[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/)**.
+At the time of writing, the only fully supported way of running DiracX is through **[Kubernetes](https://kubernetes.io/docs/tutorials/kubernetes-basics/)**.
+
+If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. This has only been tested in conjunction with a DIRAC v9.0 deployment. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).


I think this sentence is overly conservative. We know the changes in v9.1 are unrelated it's more likely to be affected by diracx updates (e.g. #842) though even then it shouldn't be too bad.

Suggested change

If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. This has only been tested in conjunction with a DIRAC v9.0 deployment. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).

If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).

chrisburr · 2026-03-27T07:34:36Z

        - admin/how-to/install/index.md
        - Minimal requirements: admin/how-to/install/minimal-requirements.md
        - Installing kubernetes: admin/how-to/install/install-kubernetes.md
+        - Preparing a container node: admin/how-to/install/prepare-container-node.md


I think we need a way of making the table of contents clearer, maybe Alt: or something as a prefix to make clear it's an alternative to the previous? Or maybe just having a single page after Minimal requirements named Installing without kubernetes or something?

chrisburr · 2026-03-27T07:36:18Z

+DIRACX_DB_URL_JOBDB=mysql+aiomysql://YourUser:YourPassword@host.containers.internal:3306/JobDB
+DIRACX_DB_URL_JOBLOGGINGDB=mysql+aiomysql://YourUser:YourPassword@host.containers.internal:3306/JobLoggingDB
+DIRACX_DB_URL_PILOTAGENTSDB=mysql+aiomysql://YourUser:YourPassword@host.containers.internal:3306/PilotAgentsDB
+DIRACX_DB_URL_SANDBOXMETADATADB=mysql+aiomysql://YourUser:YourPassword@host.containers.internal:3306/SandboxMetadataDB


This needs to be generated automatically to stay up to date for the DIRACX_*DB_URL and DIRACX_SERVICE_*_ENABLED variables.

In the sense that you might code some new ones ? In that case, that will be step two

This is probably a little out of scope for here, but any chance we could get a generic base URL environment variable for the DBs? i.e. if we had DIRACX_DB_BASE_URL=mysql+aiomysql://user:pass@myhost:3306/ which was used to construct the URLs for the databases by appending the default name (if the more specific environment variable wasn't set) then maybe we wouldn't necessarily need to maintain a full list of them here (although it isn't clear to me whether it'd do the required CREATE DATABASE step when a new one is added?).

In the sense that you might code some new ones ? In that case, that will be step two

There will definitely be new ones. There are already ways to generate this, IIUC it's about extending https://github.com/DIRACGrid/diracx/blob/main/scripts/generate_settings_docs.py

This is probably a little out of scope for here, but any chance we could get a generic base URL environment variable for the DBs? i.e. if we had DIRACX_DB_BASE_URL=mysql+aiomysql://user:pass@myhost:3306/ which was used to construct the URLs for the databases by appending the default name (if the more specific environment variable wasn't set) then maybe we wouldn't necessarily need to maintain a full list of them here (although it isn't clear to me whether it'd do the required CREATE DATABASE step when a new one is added?).

At a first sight it seems like the better approach, I let someone else reply on this as there is probably an issue that I am not aware of.

chrisburr · 2026-03-27T07:41:01Z

+set -e
+echo "Welcome to the dark side"
+
+eval "$(micromamba shell hook --shell=posix)" && micromamba activate base


This is now outdated by #810

Is this true for v9.0 as well ? As we at the moment only state it works for that.

I guess we need to test that first.

chrisburr · 2026-03-27T07:41:53Z

+eval "$(micromamba shell hook --shell=posix)" && micromamba activate base
+
+# this sets it up so that we can make changes to the code
+pip install -e /diracx_sources/diracx-core \


This and a few other bits will be outdated by #842

Should be addressed in latest update, at least it seems to work with v0.0.12 -- would that be good enough for a first pass ?

chrisburr · 2026-03-27T07:47:45Z

+```
+git clone https://github.com/DIRACGrid/diracx.git
+git checkout v0.0.2 # (note: the version matches image: ghcr.io/diracgrid/diracx/services:v0.0.2 in
+ the yaml file)
+```


This should be using an annotation, hopefully I've remembered the correct syntax:

Suggested change

```

git clone https://github.com/DIRACGrid/diracx.git

git checkout v0.0.2 # (note: the version matches image: ghcr.io/diracgrid/diracx/services:v0.0.2 in

the yaml file)

```

<div class="annotate" markdown>

```bash

git clone https://github.com/DIRACGrid/diracx.git

git checkout v0.0.2 (1)

```</div>

1. The version should match image: `ghcr.io/diracgrid/diracx/services:v0.0.2` in the yaml file

marianne013 · 2026-03-27T11:35:37Z

Hi @fstagni , @chrisburr This has now a lot of comments, and I am not sure we can re-organize the whole documentation on top of that. Can I suggest that I address all immediate issues (text, links etc) and we publish it in the location it's currently at, and make the re-organisation a separate issue ("2 points") ?

aldbr · 2026-04-16T09:45:53Z

ddev meeting
As we have bunch of people reading the documentation now, @chrisburr and @fstagni suggest we should apply the changes within this PR. They will recheck the comments, and will review it again to give more explicit instructions.

Co-authored-by: Federico Stagni <federico.stagni@cern.ch> Co-authored-by: Chris Burr <chrisburr@users.noreply.github.com>

Moves the container-based install docs into an "Installation without Kubernetes" section with its own index and a tailored minimal requirements page. Shared steps (Convert CS, Register VO, Embracing) link across to the main install section to avoid duplication.

chrisburr · 2026-04-16T10:06:08Z

I've pushed a suggestion for the layout change, what do you think?

fstagni · 2026-04-16T12:56:19Z

I've pushed a suggestion for the layout change, what do you think?

It does not solve, IMHO. Also some links are broken now. I will push myself.

fstagni · 2026-04-16T14:06:42Z

+
+Note: The username and password will then re-appear in the `diracx.env` connection strings for the databases.
+
+You can now continue to [Convert CS](../convert-cs.md). After this please read [Installing DiracX](../installing.md) for some background information before proceeding to [Installing DiracX in a container](installing-in-a-container.md).


After this please read Installing DiracX for some background information before proceeding to

This is rather confusing. Which info should be gathered from that document, which contains (also) kubernetes specific info?

…ation

fstagni · 2026-04-16T14:16:43Z

I've pushed a suggestion for the layout change, what do you think?

It does not solve, IMHO. Also some links are broken now. I will push myself.

I pushed a new schema. Have a look.

fstagni reviewed Mar 24, 2026

View reviewed changes

aldbr linked an issue Mar 25, 2026 that may be closed by this pull request

[Feature]: Provide documentation to deploy diracx in a container instead of kubernetes #798

Open

1 task

chrisburr reviewed Mar 27, 2026

View reviewed changes

chrisburr marked this pull request as draft March 27, 2026 07:50

marianne013 force-pushed the containerdoc branch 2 times, most recently from 2693e7c to 733cbe9 Compare April 1, 2026 15:42

marianne013 and others added 2 commits April 16, 2026 11:45

feat: add documentation for diracx container deployment

db9820a

Co-authored-by: Federico Stagni <federico.stagni@cern.ch> Co-authored-by: Chris Burr <chrisburr@users.noreply.github.com>

chrisburr force-pushed the containerdoc branch from 5000a84 to 5caabab Compare April 16, 2026 10:04

fstagni force-pushed the containerdoc branch from 2b82228 to 1a454eb Compare April 16, 2026 14:02

fstagni reviewed Apr 16, 2026

View reviewed changes

docs: better structure when adding the diracx in a container document…

848aa17

…ation

fstagni force-pushed the containerdoc branch from 1a454eb to 848aa17 Compare April 16, 2026 14:12

	If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. This has only been tested in conjunction with a DIRAC v9.0 deployment. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).
	If you need to decouple your DIRAC v9 upgrade from a kubernetes deployment, you can deploy DiracX in a container. In this case, your starting point is: [Prepare a node for container deployment](prepare-container-node.md).


		Note: The username and password will then re-appear in the `diracx.env` connection strings for the databases.

		You can now continue to [Convert CS](../convert-cs.md). After this please read [Installing DiracX](../installing.md) for some background information before proceeding to [Installing DiracX in a container](installing-in-a-container.md).

Conversation

marianne013 commented Mar 24, 2026

Uh oh!

read-the-docs-community bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marianne013 commented Mar 27, 2026

Uh oh!

aldbr commented Apr 16, 2026

Uh oh!

chrisburr commented Apr 16, 2026

Uh oh!

fstagni commented Apr 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fstagni commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

read-the-docs-community bot commented Mar 24, 2026 •

edited

Loading