Installation

Getting WebDAQ onto a machine, and starting it the way the control room expects. If the machine is already set up and you only need to start the application, skip to section 4.

1. What the machine needs


Operating system	Linux for a DAQ machine; macOS works for development.
CAEN libraries	CAENVMElib, CAENComm and CAENDigitizer, for real hardware. Without them WebDAQ still runs in test mode with simulated boards.
Build tools	`git`, `cmake`, `make`, a C++ compiler, `curl`. The installer puts them in place on a fresh machine.
conda	Miniforge, installed by the installer if no conda is present. Everything lives in an environment called `luna`.
ROOT	Comes from the `luna` environment. It is needed for the spectra and for the offline converter.

Nothing runs in Docker, and there is no container to start. Acquisition happens inside the server process through CaenDAQ.

Note

Versions before 4.0 ran acquisition as XDAQ inside a Docker container, with a separate spy server on port 6060. If a procedure tells you to start a container or to check port 6060, it predates 4.0 and does not apply.

2. Installing

git clone https://github.com/skowrons94/WebDAQ.git
cd WebDAQ
./install.sh

The installer is idempotent — every step checks whether the work is already done, so running it again after an update is safe. It:

installs the system build tools;
checks out the two C++ submodules, CaenDAQ (the acquisition backend) and RUReader (the offline .caendat → ROOT converter);
installs Miniforge if conda is missing;
creates the luna environment from environment.yml;
builds RUReader and installs the caendaq Python module into the environment;
writes frontend/.env and builds the web interface;
adds a LunaDAQ launcher to your ~/.bashrc.

Open a new terminal afterwards, or source ~/.bashrc, so the launcher is on your PATH.

The API address is baked into the frontend at build time. frontend/.env holds NEXT_PUBLIC_API_URL, and Next.js compiles it into the bundle. If the DAQ server will be reached from other machines, set it to an address those machines can resolve — not 127.0.0.1 — and rebuild:

cd frontend
npm run build

Forgetting the rebuild is the most common deployment mistake: the interface loads and then fails every request, because the old address is still inside it.

3. The working directory

The working directory is the experiment. Everything the server reads and writes is relative to the directory it was started in: conf/ (board configurations, the histogram dashboard, credentials), calib/, data/ and the app.db database. Two working directories are two independent experiments that share one installation.

You do not have to create any of it by hand. The first launch creates the directories, brings the database schema up and creates a default user, so an empty directory is a valid starting point for a new campaign.

4. Starting it

4.1 With the launcher

LunaDAQ            # start the web interface in the background (freeing its port first)
LunaDAQ status     # what is holding each port
LunaDAQ stop       # stop both parts, politely then firmly
LunaDAQ restart    # stop both, start the interface, and the DAQ server again in its folder
LunaDAQ logs       # follow the interface's log (Ctrl-C to leave)
LunaDAQ run        # start the interface in this terminal instead
LunaDAQ backend    # run the DAQ server in this terminal, for debugging

LunaDAQ (or LunaDAQ start) returns once the interface answers, and the interface keeps running after the terminal or the SSH connection is closed. Its output goes to ~/.local/state/lunadaq/frontend.log. Typed again while the interface runs, it leaves it alone. Stopping the interface also stops the DAQ server it started, and with it a run in progress, so stop and restart refuse while a run is going: stop the run first, or add --force.

Then open http://localhost:3000 and log in. The DAQ Server badge at the top right starts the server itself: pick the working directory for the campaign and press Start. The badge is also on the login page, so the server can be started before anyone logs in.

LunaDAQ stop only ever stops processes that look like ours — an unrelated program on port 3000 is reported and left alone, which is why it is a better answer to a busy port than killing whatever holds it.

4.2 Running it inside tmux

LunaDAQ already runs in the background. To watch its output live instead, run it in the foreground inside tmux, a session that keeps running on the machine whether or not anyone is attached to it:

tmux new -s daq        # create a session called "daq" and attach to it
LunaDAQ run            # start the interface inside it, in the foreground

Now detach and leave it running: press Ctrl-b, release both keys, then press d. You are back at your own shell; the session is still running.

What you want	How
List the sessions on the machine	`tmux ls`
Attach to the session again	`tmux attach -t daq`
Detach and leave it running	Ctrl-b then d
Scroll back through the output	Ctrl-b then [, then the arrow keys or PageUp; q leaves scroll mode
Open a second window in the session	Ctrl-b then c; switch with Ctrl-b then 0, 1, …
Close the current window	type `exit` in it
Stop the whole session	attach, stop the application with `LunaDAQ stop`, then `exit`

Every tmux command is the prefix Ctrl-b followed by one key; that is the only thing worth memorising. If a session is already attached somewhere else — somebody left it open — tmux attach -d -t daq takes it over.

A detached session survives a dropped SSH connection, but not a reboot of the DAQ machine. After a reboot, attach to a new session and start it again.

5. Without hardware

TEST_FLAG=True LunaDAQ backend

or tick Test Mode in the DAQ Server panel before starting the server. Test mode fabricates CAEN-style data for simulated boards and simulates the picoammeter, so the whole chain — readout, data file, spectra, rates, run metadata — works on a laptop with no digitizers attached.

Set the variable or leave it unset; never set it to False. Most of the code reads it as “any value at all means test mode”, so TEST_FLAG=False puts the server into test mode while one part of it believes the hardware is real.

6. Checking the installation

With the server running and a login in hand:

Check	Where
The server answers	The DAQ Server badge reads DAQ Server Online.
The boards answer	Settings → Boards: each board shows Connected. Use Scan for boards to find them rather than typing their settings from memory.
The acquisition module is installed	DAQ → Hardware Info names the CaenDAQ version, and says `hardware` rather than `mock / test mode`.
A run works	Take a short run with saving on, then open it in the Logbook: there should be a `.caendat` file and, with a current module configured, a `current.txt`.
The converter is installed	Logbook → the run → Convert offers options instead of RUReader is not installed.

The server’s own log is server.log in the working directory it was started in, and the interface can show it: DAQ Server → Show logs.

7. Updating an installation

cd WebDAQ
git pull
git submodule update --init --recursive
conda activate luna
pip install server/native/caendaq     # only if the submodule moved
cd frontend && npm run build
LunaDAQ restart

The database schema is brought up to date every time the server starts, so there is nothing to migrate by hand. migrations/ is part of the repository — do not delete it, and do not run flask db init; that is how a schema history gets thrown away.

8. If the installation itself fails

Symptom	Usual cause
`caendaq` cannot be imported	The module was built into a different environment. `conda activate luna`, then `pip install server/native/caendaq`.
`No module named flask` when running the tests	The same thing, from the other direction: the shell is not in the `luna` environment.
Port 5001 or 3000 is in use	`LunaDAQ status` names what holds it; `LunaDAQ stop` clears our own leftovers. A port held by an unrelated program is reported, not killed.
The interface loads but every request fails	`NEXT_PUBLIC_API_URL` points somewhere the browser cannot reach, or the frontend was not rebuilt after it changed.
The boards are listed but never connect	The CAEN libraries are missing, or another process still holds the links — including a WebDAQ backend that did not exit.

Troubleshooting covers what to do once it is installed and something stops working during a shift.