One app#

Every installed app has its own page. It opens from Manage on the app's catalogue card, from its card on the Installed tab, from its entry in the navigation when it has one, and from search.

The app's settings are changed with Edit settings, and Stop, Start and Uninstall are changes too: each adds to the pending changes, which are applied with Apply changes in the bar at the bottom of the page. Check for update and Restart act at once.

The header#

The page is titled with the app's name in the catalogue, with its one-line description beneath. It has two tabs, Overview and Log, and a third, Configuration, in Advanced mode. Beside them:

Control	Does
Open ↗	Opens the app's web interface, for an app that has one and an address.
Badge	The app's state, as on the Installed tab.
Edit settings	Opens the settings editor. See Editing settings.
Check for update	For a running app: downloads its image again, and says whether it changed.
Restart	For a running app: restarts it at once.
Stop or Start	Adds stopping or starting the app to the pending changes.
Uninstall	Adds the app's removal to the pending changes, after a second press to confirm.

Every control except Open ↗ needs the operator role; a viewer sees them disabled.

The tiles#

Tile	Shows
State	Running, Stopped or Not running, with the container's status beneath.
Health check	Healthy, Not healthy or Not checked, with the result of the last check beneath.
Address	The app's address, with "App network" beneath, or "Router" with "Uses the router's own network".
Image	The image's name, with the end of its reference beneath: the tag, or the digest for a pinned image.

Settings and state differ#

When the app's settings and what is running disagree, the panel Settings and state differ appears below the tiles. It shows the state badge, a sentence describing the difference, and when that was checked, such as "checked 5s ago". Its buttons close the difference:

The sentence	Buttons
"adguard is set to run, but it is not running", with the container's status	Restart now starts the app at once, without changing its settings. Set to stopped adds a change that stops the app in its settings, so they match what is running.
"adguard is stopped in its settings, but it is running", with the container's status	Set to running adds a change that sets the app to run, so its settings match what is running.

To stop an app that is stopped in its settings but running, press Set to running and apply the change, then press Stop and apply that change: the two must be applied separately. Advanced mode shows this fix as Stop it, with its two commands.

For a change added here, the notice says "Change saved — It takes effect when you apply pending changes."

Overview#

Panel	Shows
Details	Name; Image, the full reference; Image ID, Image created and Image size when the image is on the router; Network, the app's address or "The router's own network"; Status; and Web interface, a link, for an app that has one.
Environment variables	Each variable's Name and Value. A secret value reads "Hidden".
Published ports	Each port's Name, Router port, App port and Protocol.
Storage	Each folder's Name, Folder on the router, Folder in the app, and Access: Read only, or Read and write.
About	The catalogue's description of the app, its badges, Documentation ↗, and the catalogue's notes.
Integrations	The offers the app makes, each linking to the page it appears on, with its text. See Integration offers.

About appears for an app from the catalogue, and Integrations for one that makes offers. Details, Environment variables, Published ports and Storage each have an Edit button, which opens the settings editor.

An app with no published ports shows "No published ports.", or, on the router's own network, "The app uses the router's own network, so it needs no published ports." An app with no storage shows "No storage. Files the app writes are not kept when it is recreated."

Editing settings#

Edit settings opens a panel titled Edit and the app's name.

Section	Fields
Image	Image, the image reference. "A new image is downloaded to the router when you save."
Network	Use the router's own network; with it off, Address, an address in the app network, 10.99.0.0/24.
Environment variables	A row for each variable: Name, Value and Remove. Add variable adds a row.
Published ports	A row for each port: Name, Router port, App port, Protocol (TCP or UDP) and Remove. Add port adds a row. A port field takes a port or a range, such as 10025-10030.
Storage	A row for each folder: Name, Folder on the router, Folder in the app, Access (Read and write, or Read only) and Remove. Add volume adds a row.

The name of a variable, port or folder the app already has cannot be changed: remove the row and add a new one.

Save changes is enabled once something has changed and every field is valid. It then:

downloads the new image to the router, if Image changed (Downloading image…);
creates the folders on the router for storage that is new or has moved (Creating folders…). A folder that exists is left as it is. New folders can be created only under /config; a folder anywhere else has to exist already, or saving stops with "The folder /srv/data does not exist, and new folders can only be created under /config.";
adds the difference to the pending changes (Saving…). The notice says "Changes saved — They take effect when you apply pending changes."

The change reads, for example, "Change app “adguard”", with "Add variable TZ, remove port web" beneath. Moving an app from the router's own network to the app network also adds the app network, when the router does not have it yet. If a step fails, the panel shows Not saved with the reason. Advanced mode shows the commands under Commands.

Each field is checked as it is typed, before anything is saved. The messages include:

"Enter an image reference, such as docker.io/library/nginx:latest."
"Enter an IPv4 address, such as 10.99.0.10." and "Enter an address in 10.99.0.0/24."
"Use letters, digits, hyphens and underscores only.", for the name of a variable, port or folder
"There is already a variable called TZ."
"Enter a port from 1 to 65535, or a range such as 10025-10030."
"Enter a full path, starting with /." and "Paths may not contain spaces or shell characters."

Secret variables#

An environment variable whose name contains PASS, PWD, TOKEN, KEY, SECRET, AUTH, CREDENTIAL or PRIVATE is secret. Its value is never read back to the browser, for any role:

Environment variables shows "Hidden" for it.
In the editor its Value is empty, with "Hidden. Leave empty to keep it." and the placeholder "Unchanged". A value typed there replaces it.
A new variable whose name marks it as secret is typed hidden.
The change's description in the pending changes names the variable, never its value.
The Configuration tab, and the raw settings in the API, show "[redacted]" in its place.

Before 0.9.1, the raw settings in the API carried these values to every role, viewers included.

Check for update#

Check for update downloads the app's image again, fetching only what has changed, and compares the image on the router before and after. The notice says "Image is up to date", or "Newer image downloaded — Restart the app to use it.", and the page then shows "A newer image has been downloaded. Restart the app to use it." The app keeps running on the image it started with until it is restarted.

Every image in the catalogue is pinned by digest, so for an app installed from the catalogue the check finds the same image. To run a different image, change Image in Edit settings.

The check is recorded in the audit log.

Restart#

Restart restarts the app at once, as Restart on its card on the Installed tab does. It changes no settings, adds nothing to the pending changes and writes no revision; the restart is recorded in the audit log. The notice says "Restarted", with a sentence such as "adguard was restarted. Its settings did not change." Wheelhouse then reads the app's status, and says so if the app is not running.

An agent that does not run on the router restarts the app by stopping and starting it instead: two changes, applied one after the other, each a revision in the history. The notice then says "Restarted by stopping and starting the app; both changes are in the history." If the start fails, the message says the app is not running.

Stop, start and uninstall#

Stop adds "Stop app “adguard”" to the pending changes; the notice says "Stop saved — The app stops when you apply pending changes." On a stopped app, Start adds "Start app “adguard”". A stopped app keeps all of its settings.

Uninstall asks for a second press, Uninstall AdGuard Home?, then adds "Remove app “adguard”" to the pending changes. When it is the last app on the app network, "Remove app network “apps”" is added with it. The notice says "Uninstall saved — Its files on the router are kept. It is removed when you apply pending changes."

Uninstalling keeps:

the app's folders on the router, such as /config/apps/adguard, with its data. Installing the app again uses the same folders and picks up that data. The web UI does not delete an app's folders;
the app's image, which can be removed on the Images tab;
settings on other pages that point at the app, such as a change added from one of its offers. Remove those separately.

Log#

The Log tab shows the app's output in the Log panel, with the number of lines. It follows new lines every 5 seconds: the button reads Following, and the indicator "following". Press the button to pause; Follow resumes. An app with no output shows "No log entries."

An app that is set to run but is not running has usually said why in its log.

Configuration#

In Advanced mode, the Configuration tab shows the app's settings as the router holds them, with the value of each secret variable replaced by "[redacted]".

An app that is not installed#

The page for a name that is not installed shows "App not installed" and "No app named … is installed on this router.", with Back to Apps.

For automation#

Call	Answers or does
`GET /api/apps/installed`	Every installed app, with its settings (secret values left out), state, health and verdict.
`GET /api/apps/logs/{name}`	The app's log lines.
`POST /api/apps/update`	Check for update, from `{"name": "adguard"}`.
`POST /api/containers/{name}/restart`	Restart.
`POST /api/apps/pull`	Downloads an image, from `{"image": "docker.io/library/nginx:latest"}`.
`POST /api/apps/prepare`	Creates folders for new storage, from `{"directories": ["/config/apps/adguard/backup"]}`. New folders only under /config.
`POST /api/stage`	Adds operations to the pending changes, as Save changes, Stop, Start and Uninstall do.

The reads need no more than the viewer role; every other call needs the operator role and a licence.