Get started

Docker installation

Deploy NasDash on port 2504 with persistent data and optional Docker connections.

NasDash uses port 2504 on the Docker host and 2504 inside the container. The copy-ready Compose file stores data in ./data. Do not replace that folder with a named volume on an existing installation.

Docker management is optional. Choose Portainer, Dockhand, an HTTP(S) Docker-compatible API, or a Unix socket. The local socket proxy is one option; Portainer and Dockhand do not require it. See Docker connections.

Copy-ready Docker Compose

services:
  nasdash:
    image: ghcr.io/lucas-lepajollec/nasdash:latest
    ports:
      - "2504:2504"
    env_file:
      - path: .env
        required: false
    volumes:
      - ./data:/app/data
    pid: host
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

  # Optional local engine connection: docker compose --profile docker-proxy up -d
  docker-proxy:
    profiles: ["docker-proxy"]
    image: tecnativa/docker-socket-proxy:v0.5.0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      VOLUMES: 1
      NETWORKS: 1
      INFO: 1
      POST: 1
      DELETE: 0
    restart: unless-stopped

Save this as docker-compose.yml. Before starting, prepare access to the data directory. The commands below apply to a new empty Linux directory and the default UID:GID only. For existing data, a custom user or Synology ACLs, follow the permissions section below first.

mkdir -p ./data
sudo chown 1001:1001 ./data
sudo chmod 700 ./data
docker compose pull
docker compose up -d --force-recreate
docker compose ps
docker compose logs nasdash

Open http://192.0.2.10:2504 from the LAN (replace the example address) or http://localhost:2504 on the host. Enter the setup code and follow the first-start guide. No Docker connection is required to start NasDash.

The default command starts NasDash alone. For the optional local proxy, run the command below, then choose Address in Settings → Integrations → Docker. Enter docker-proxy in the host field and 2375 in the port field; the resulting endpoint is http://docker-proxy:2375. Keep the profile enabled on recreates and preserve the existing data mount.

docker compose --profile docker-proxy up -d

The optional proxy publishes no host port; DELETE=0 disables deletions. pid: host shares host process visibility and can be removed when unnecessary; remote monitoring does not require it. host.docker.internal reaches services on the host. Never publish an unauthenticated Docker API.

On a fresh installation, NasDash starts in private mode, creates only admin, persists its cryptographic keys and prints Setup code: XXXX-XXXX-XXXX once in the logs. This code is the first administrator password; NASDASH_ADMIN_PASSWORD replaces it if set. The optional .env is for advanced overrides. Home starts with a clock and a weather widget even if the guide is skipped, with no sample services, devices or Docker host. Existing installations keep their settings and accounts.

Existing named-volume installation

Keep nasdash-data:/app/data only if the instance already uses that named volume. Do not switch storage types during a routine image update.

Stop without deleting data

docker compose stop
docker compose down

Do not add -v during a normal stop. See Docker and proxy and Updates.

Synology and data-folder permissions

The image runs as UID:GID 1001:1001. Before the first start, create the host data folder and grant that identity read/write access. On Synology, use a dedicated DSM account with read/write ACLs on this folder. Run id nasdash-user over SSH (replace the example account name), then add its numeric identity to the NasDash service only. The following fragment is an example, not universal NAS values:

services:
  nasdash:
    user: "1026:100"

Keep the complete Compose file and existing data mount. Create the folder before starting; also check inherited ACLs, parent-directory traversal, existing files and logos. PUID/PGID variables are not supported. Changing user does not transfer ownership. Do not use root, chmod 777, or delete data to fix access. A rebuild cannot repair host permissions. If an older Compose rejects env_file.required, remove the whole optional block when not using .env, or use env_file: .env with your existing file.

On Linux, prepare a new empty ./data with mkdir -p ./data, sudo chown 1001:1001 ./data, and sudo chmod 700 ./data. Back up and stop existing installations before changing access; keep their data mount.

Images from version 0.2.2 onward check access before startup and report the actual runtime UID:GID if data, logos or existing files are inaccessible. Correct the folder permissions and recreate the container. Linux Docker UID/GID tests do not substitute for real DSM validation.

Synology · Compose user