Self-hosting
Advanced setup
The default installation is enough to start writing. Use these options when you need more control over storage, backups or access.
Portainer on a NAS
Use the official Stack in a Docker Standalone environment. Keep its two named volumes for projects and settings; Samples stays read-only inside the image. On a NAS, localhost is the NAS itself. For browser access from another computer, follow the NPM setup below or use the existing host-installed Nginx profile.
Portainer backups reuse the selected container’s actual volumes, settings and image. Keep the existing Stack and volume names when upgrading.
Custom project storage
The supplied Docker configuration keeps your projects and application settings in two named volumes. Most users can keep these defaults. Save in selects a folder on the machine running Nariqui; your browser does not give it access to another computer’s disk.
To add your own folder, first check the image’s runtime user and group:
docker image inspect ghcr.io/aurelica/nariqui:latest --format '{{.Config.User}}'Ask the Docker host’s administrator to create /srv/nariqui/projects and give that UID/GID permission to use it. Keep it private rather than world-writable. This example uses a Linux host path; with Docker Desktop, choose a host folder Docker can share and change only the example’s source path.
Save this YAML as compose.storage.yaml beside your existing compose.yaml:
services:
nariqui:
volumes:
- type: bind
source: /srv/nariqui/projects
target: /var/lib/nariqui/writing
bind:
create_host_path: false
environment:
NARIQUI_PROJECT_ROOTS_JSON: '{"projects":"/var/lib/nariqui/projects","my-writing":"/var/lib/nariqui/writing","samples":"/app/samples"}'source is the folder on your Docker host. target is where the same folder appears inside the container. NARIQUI_PROJECT_ROOTS_JSON uses container paths and names the locations you can select in Nariqui. This example adds My writing, while keeping the original Projects and read-only Samples locations.
Check the combined configuration, then start it:
docker compose -f compose.yaml -f compose.storage.yaml config
docker compose -f compose.yaml -f compose.storage.yaml up --detach --no-build --pull neverKeep the original state/project volumes, loopback port binding and NARIQUI_READ_ONLY_ROOTS_JSON Samples protection. Use both -f arguments for later start, stop and maintenance commands too, including the backup commands below. Choose Save in → My writing to use the added folder.
Keep active SQLite projects on a reliable local drive. NFS/SMB network storage has different locking and sync behavior, so use it for verified backup/export copies unless you have validated your particular setup. A mounted folder is not a backup. Do not mount the Docker socket, your whole filesystem, home directories or unrelated credentials as a project location.
Backups and recovery
A complete recovery set contains your native projects and the application settings needed to recover the installation. Make one before important work and before upgrades. Portable .qui copies protect individual projects; they do not replace a complete recovery set.
Create a private-backups folder beside compose.yaml. Give the image’s runtime UID/GID write access and restrict it to that owner (0700). On a Linux host, the administrator may need to set its ownership; a folder owned only by your login user may not be writable by the container. Use the image inspection command above to check the identity.
Run the appropriate block on the Docker host, where private-backups exists. Both use the app container’s actual mounts and image, stop it, back up, verify and restart. Any error aborts the block. After Nariqui is stopped, it stays stopped until you resolve the error.
Docker Compose backup commands
Use your original installation folder and the same project/configuration as startup. If you used -p or additional -f files, include them in the first docker compose line. An absent or wrong container stops the block; it never creates replacement data volumes.
(
set -euo pipefail
container=$(docker compose ps -q nariqui)
: "${container:?Select the running Nariqui container}"
container=$(docker inspect --format '{{.Id}}' "$container")
service=$(docker inspect --format '{{index .Config.Labels "com.docker.compose.service"}}' "$container")
[[ "$service" == nariqui ]]
image=$(docker inspect --format '{{.Image}}' "$container")
test -d "$PWD/private-backups"
settings=$(mktemp)
trap 'rm -f "$settings"' EXIT
docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$container" |
sed -n '/^NARIQUI_PROJECT_ROOTS_JSON=/p; /^NARIQUI_READ_ONLY_ROOTS_JSON=/p; /^NARIQUI_APPLICATION_STATE_DIR=/p' > "$settings"
grep -q '^NARIQUI_APPLICATION_STATE_DIR=' "$settings"
name="recovery-$(date +%Y%m%d-%H%M%S)"
helper=(docker run --rm --pull never --read-only --tmpfs /tmp:mode=1777,noexec,nosuid,size=64m --cap-drop ALL
--security-opt no-new-privileges:true --volumes-from "$container" --env-file "$settings")
docker stop "$container"
"${helper[@]}" --mount "type=bind,src=$PWD/private-backups,dst=/backup" \
"$image" python -c 'from nariqui_server.maintenance import main; raise SystemExit(main())' backup "/backup/$name"
"${helper[@]}" --mount "type=bind,src=$PWD/private-backups,dst=/backup,readonly" \
"$image" python -c 'from nariqui_server.maintenance import main; raise SystemExit(main())' verify "/backup/$name"
docker start "$container"
)Portainer backup commands
In Portainer, open Nariqui’s container and copy its container ID. Run this on that same Docker host and enter the ID. The backup folder is on the server, not your browser’s computer. No Stack export or guessed volume names are needed.
(
set -euo pipefail
read -r -p "Nariqui container ID from Portainer: " container
: "${container:?Select the running Nariqui container}"
container=$(docker inspect --format '{{.Id}}' "$container")
service=$(docker inspect --format '{{index .Config.Labels "com.docker.compose.service"}}' "$container")
[[ "$service" == nariqui ]]
image=$(docker inspect --format '{{.Image}}' "$container")
test -d "$PWD/private-backups"
settings=$(mktemp)
trap 'rm -f "$settings"' EXIT
docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$container" |
sed -n '/^NARIQUI_PROJECT_ROOTS_JSON=/p; /^NARIQUI_READ_ONLY_ROOTS_JSON=/p; /^NARIQUI_APPLICATION_STATE_DIR=/p' > "$settings"
grep -q '^NARIQUI_APPLICATION_STATE_DIR=' "$settings"
name="recovery-$(date +%Y%m%d-%H%M%S)"
helper=(docker run --rm --pull never --read-only --tmpfs /tmp:mode=1777,noexec,nosuid,size=64m --cap-drop ALL
--security-opt no-new-privileges:true --volumes-from "$container" --env-file "$settings")
docker stop "$container"
"${helper[@]}" --mount "type=bind,src=$PWD/private-backups,dst=/backup" \
"$image" python -c 'from nariqui_server.maintenance import main; raise SystemExit(main())' backup "/backup/$name"
"${helper[@]}" --mount "type=bind,src=$PWD/private-backups,dst=/backup,readonly" \
"$image" python -c 'from nariqui_server.maintenance import main; raise SystemExit(main())' verify "/backup/$name"
docker start "$container"
)Keep a separate protected copy of the whole recovery folder, preferably encrypted and off the Docker host. It can contain both encrypted AI credentials and the key needed to read them. Keep it out of Git, logs, release files and public storage. Backup scheduling and copying to another host are your responsibility.
Restoring your installation
Use the full Offline backup and clean-host recovery instructions in nariqui-install/INSTALL.md, available in the optional offline archive. It includes the supported maintenance restore command and the Compose state-directory settings.
Restore into a stopped, clean installation with fresh empty project roots and matching location aliases. Project destinations and the application-state directory must be absent; the fresh state volume needs a new, absent child directory for restored state. Keep that state-directory setting for later starts. Never restore over active projects or populated data volumes.
After restoring, check service health and open each project to check its writing, planning and media before retiring your old installation or backups.
docker compose down --volumes deletes the named project and state volumes. To stop without deleting data, use docker compose stop nariqui; restart with docker compose start nariqui.
Upgrades
Upgrading from an earlier Beta: save and close open projects, retain the same browser profile and URL, and make a complete backup before changing images. Keep the existing Compose project or Portainer stack, project/state volumes, origin allowlists and authenticated proxy settings. Use ghcr.io/aurelica/nariqui:0.3.0-Beta, then pull and recreate the service. In Portainer, update the existing stack and select re-pull image; do not create a second stack. Never remove volumes with down -v. Verify health and reopen a disposable saved project before important writing. For rollback, retain the old image/configuration and restore the pre-upgrade backup to a separate destination rather than overwriting newer work.
Save and close your projects, then make and verify a backup first. Keep the same Compose folder or Portainer stack name and both existing volumes. Keep the previous image digest and configuration for recovery. Never use down --volumes during an upgrade.
With Compose, run docker compose pull nariqui, then docker compose up -d nariqui. With Portainer, update the existing Stack and choose the option to re-pull the image and redeploy. Reopen your projects and check your settings. The :latest tag does not update a running container by itself.
For a fixed release, replace :latest with :0.3.0-Beta, or use ghcr.io/aurelica/nariqui@sha256:… with the published registry digest. Version tags are retained without moving; digests identify exact registry content. Keep automatic image updaters off. To roll back, use the previous image with a verified pre-upgrade backup in clean storage; do not downgrade newer project data in place.
Moving from the archive installation? In your existing Compose file or Stack, replace only the image value with ghcr.io/aurelica/nariqui:latest, remove pull_policy: never and any build section, then use the upgrade steps above. Preserve all existing storage, environment and proxy settings; do not create a second Stack.
Optional: offline archive and verification
Registry installation needs none of these steps. Use the signed archive for offline transport or independent verification. Obtain the archive, checksum, signature and publisher key from the official release. The archive also includes deployment/recovery documentation and the matching third-party compliance material.
Docker offline archive · Checksum · Signature · Publisher key · Third-party notices
Use Bash, GnuPG, tar and a SHA-256 checker on a trusted online computer to prepare the files. Independently confirm the full publisher fingerprint before accepting a signature. Stop if verification fails; retain the complete archive and legal/compliance files for offline use.
Verify and extract the archive
gpg --import publisher-key.asc
gpg --fingerprint 2F5BBFE687AD7052AD0AF7D22069BC5DB8E66B80
# Confirm the full fingerprint independently before continuing.
gpg --verify "nariqui-0.3.0-Beta-linux-amd64.tar.gz.asc" "nariqui-0.3.0-Beta-linux-amd64.tar.gz"
if command -v sha256sum >/dev/null 2>&1; then
sha256sum --check "nariqui-0.3.0-Beta-linux-amd64.tar.gz.sha256"
else
shasum -a 256 --check "nariqui-0.3.0-Beta-linux-amd64.tar.gz.sha256"
fi
tar -xzf "nariqui-0.3.0-Beta-linux-amd64.tar.gz"
cd nariqui-0.3.0-Beta(
set -euo pipefail
if [[ -f SHA256SUMS.asc ]]; then
gpg --verify SHA256SUMS.asc SHA256SUMS
fi
if command -v sha256sum >/dev/null 2>&1; then
sha256sum --check SHA256SUMS
else
shasum -a 256 --check SHA256SUMS
fi
)Install the verified image without a registry
Run from the extracted release folder. Enter the manifest’s internal version (for this release, 0.3.0b0). This uses the original archive’s configuration and local image; do not substitute the registry YAML for an offline installation.
(
set -euo pipefail
read -r -p "Version in the verified release manifest: " version
[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([ab]0)?$ ]]
tar -xzf "nariqui-${version}-install.tar.gz"
cp "nariqui-install/compose.yaml" compose.yaml
loaded=$(docker image load --input "nariqui-${version}-linux-amd64.docker-image.tar")
case "$loaded" in
'Loaded image: '*) image="${loaded#Loaded image: }" ;;
'Loaded image ID: '*) image="${loaded#Loaded image ID: }" ;;
*) printf '%s\n' 'Image load was not recognised; stop.' >&2; exit 1 ;;
esac
[[ -n "$image" && "$image" != *$'\n'* ]]
docker image inspect nariqui:0.3.0-Beta >/dev/null
docker compose config --quiet
docker compose up --detach --no-build --pull never
)For offline Portainer, extract the install archive and Docker transport, import the transport under Images → Import, and paste the supplied install YAML. Remove its build section, use image: nariqui:0.3.0-Beta and pull_policy: never. Keep its storage and security settings.
LAN and VPN access with Nginx Proxy Manager
Nariqui has no built-in user authentication. Local access uses the supplied localhost-only port. For LAN or WireGuard access, use an HTTPS hostname with password authentication. A VPN alone does not replace that authentication. General Internet exposure is outside the supported Beta profile.
For containerised NPM on the same Linux Docker host, use its existing trusted Docker network. No new network or host-network mode is needed. Containers on this network and the Docker host can reach the backend directly, so only trusted administration services may share it. Keep Docker direct routing disabled.
- In Portainer, open your existing NPM container’s details and note the name of its Docker network, for example
npm_default. Use a network that already has NPM attached. - In the official Nariqui YAML, remove the entire
ports:section and its mapping. Do not replace localhost with the NAS IP or0.0.0.0. Keep the remaining storage and security settings. - Replace the two trusted-host/origin values with the example below, using your real HTTPS hostname. Retain loopback hosts for health checks. Append the network block at the YAML’s top level, alongside
servicesandvolumes, changingnpm_defaultto the actual existing network name. - Deploy Nariqui. In NPM create a password Access List, then a Proxy Host for your hostname: scheme http, Forward Hostname nariqui, Forward Port 8080. Select that Access List; leave Satisfy Any off, with no IP-only authentication bypass. Keep any path-specific custom locations subject to the same password requirement.
- Attach a valid certificate for your hostname and enable Force SSL. Use your existing LAN/VPN name resolution to reach NPM; no public router port-forward is needed. Open the HTTPS hostname and sign in.
environment:
# Replace only these two existing environment entries; keep the others.
NARIQUI_TRUSTED_HOSTS_JSON: '["127.0.0.1","localhost","writer.example.test"]'
NARIQUI_TRUSTED_ORIGINS_JSON: '["https://writer.example.test"]'networks:
default:
external: true
name: npm_default # Replace with NPM's actual existing network name.Before writing, use a private browser window to confirm both the homepage and /api/health ask for a password. After signing in, confirm healthy status and create, Save and reopen a disposable project. Nariqui must have no host-published port. A 502 usually means the wrong network or upstream name; a rejected hostname/origin means the allowlists do not match the exact HTTPS address. Do not fix either by publishing the backend or using wildcard allowlists.
This is one writer’s workspace, not separate accounts or collaboration. NPM passwords protect the whole installation. Preserve the same HTTPS hostname for browser draft recovery. The profile is tested in an isolated Docker/NPM environment; the owner must confirm their QNAP/Portainer configuration.
Alternative: existing host-installed Nginx
Keep the ordinary loopback stack and use the offline archive’s reverse-proxy/nginx.conf on the Docker host with a valid TLS certificate and Basic Authentication password file. Add its exact hostname and HTTPS origin to Nariqui’s trusted values while retaining loopback health-check hosts. The upstream is 127.0.0.1:8080, or the configured local port.
Private operator access over existing SSH
If you already have authorised SSH access, run this on your own computer. Replace the user and host with the actual Docker host selected in Portainer, which may differ from the Portainer server. Use your existing authentication and verified host key.
ssh -N -o ExitOnForwardFailure=yes \
-L 127.0.0.1:8080:127.0.0.1:8080 your-user@your-docker-hostKeep the terminal open, then visit http://127.0.0.1:8080 on your computer. Local port 8080 must be free. If SSH fails, stop rather than changing the Docker binding. This procedure does not change the regular authenticated HTTPS access requirements.
Back to installation → · Download Nariqui → · Report a problem →

