docker nextcloud client

A simple nextcloud client that runs in a docker container.

build

docker build -t docker.asperti.com/paspo/nextcloudclient .

running via docker

docker run -d \
  -v "$PWD/nextcloud:/data" \
  -e "NEXTCLOUD_USERNAME=username" \
  -e "NEXTCLOUD_PASSWORD=password" \
  -e "NEXTCLOUD_URL=https://nextcloud.example.com" \
  -e "NEXTCLOUD_DIR=/data" \
  docker.asperti.com/paspo/nextcloudclient

running with docker-compose

this is a sample docker-compose.yaml:

version: "3"
services:

  nextcloudclient:
    image: docker.asperti.com/paspo/nextcloudclient
    restart: unless-stopped
    volumes:
      - "$PWD/nextcloud:/data"
    environment:
      - NEXTCLOUD_USERNAME=username
      - NEXTCLOUD_PASSWORD=password
      - NEXTCLOUD_URL=https://nextcloud.example.com
      - NEXTCLOUD_DIR=/data

you can run this with:

docker-compose up -d

credentials from secret files

Instead of NEXTCLOUD_USERNAME / NEXTCLOUD_PASSWORD, you can point to files (e.g. Docker or Compose secrets). The client reads the first line of each file.

docker run (bind-mount secret files):

docker run -d \
  -v "$PWD/nextcloud:/data" \
  -v "$PWD/secrets/nextcloud_user.txt:/run/secrets/user:ro" \
  -v "$PWD/secrets/nextcloud_pass.txt:/run/secrets/pass:ro" \
  -e NEXTCLOUD_USERNAME_FILE=/run/secrets/user \
  -e NEXTCLOUD_PASSWORD_FILE=/run/secrets/pass \
  -e NEXTCLOUD_URL=https://nextcloud.example.com \
  docker.asperti.com/paspo/nextcloudclient

docker-compose (top-level secrets):

version: "3.9"
services:
  nextcloudclient:
    image: docker.asperti.com/paspo/nextcloudclient
    restart: unless-stopped
    volumes:
      - "$PWD/nextcloud:/data"
    secrets:
      - nc_user
      - nc_pass
    environment:
      NEXTCLOUD_USERNAME_FILE: /run/secrets/nc_user
      NEXTCLOUD_PASSWORD_FILE: /run/secrets/nc_pass
      NEXTCLOUD_URL: https://nextcloud.example.com
      NEXTCLOUD_DIR: /data
secrets:
  nc_user:
    file: ./secrets/nextcloud_user.txt
  nc_pass:
    file: ./secrets/nextcloud_pass.txt

Parameters

ENV	Default	Description
NEXTCLOUD_USERNAME	username	Nextcloud username
NEXTCLOUD_PASSWORD	password	Nextcloud password
NEXTCLOUD_USERNAME_FILE		If set, the first line of this file is used as username (overrides NEXTCLOUD_USERNAME). Must be readable or the client exits with an error.
NEXTCLOUD_PASSWORD_FILE		If set, the first line of this file is used as password (overrides NEXTCLOUD_PASSWORD). Same rules as NEXTCLOUD_USERNAME_FILE.
NEXTCLOUD_URL	https://nextcloud.example.com	Nextcloud instance URL
NEXTCLOUD_DIR	/data	Location of nextcloud data inside the container
NEXTCLOUD_DIR_CHOWN	1	If set to "1" the entire content of the $NEXTCLOUD_DIR is chown with user ID and GID
NEXTCLOUD_FORCE_TRUST		If set to "1" the client will accept untrusted https connections
NEXTCLOUD_HTTPPROXY		If set, this proxy will be used to connect to the nextcloud instance. The format is: http://server:port
NEXTCLOUD_UPLIMIT		If set, upload speed will be limited. (KB/s)
NEXTCLOUD_DOWNLIMIT		If set, download speed will be limited. (KB/s)
NEXTCLOUD_EXCLUDEFILE		Path to a file, inside the container, which contains a list of excluded directories/files
NEXTCLOUD_UNSYNCFILE		Path to a file, inside the container, which contains a list of remote unsynced folders (selective sync)
NEXTCLOUD_SILENT		If set to "1", the client will run in silent mode, with a lot less log messages
NEXTCLOUD_SLEEP	30	Seconds of sleep time between every client runs
USER_NAME	nextcloudclient	Internal username used by nextcloud client
USER_UID	1000	Internal UID used by nextcloud client
USER_GID	1000	Internal GID used by nextcloud client

Health check

The image defines a Docker HEALTHCHECK that reports healthy only when a sync run has completed successfully recently.

• After each successful nextcloudcmd run, the client updates /tmp/nextcloudclient_last_ok.
• The check treats the container as healthy if that file exists and was modified within 2 × NEXTCLOUD_SLEEP + 120 seconds (same formula as the script: two sleep intervals plus a fixed margin for long runs).
• If sync keeps failing (wrong credentials, server down, etc.), the marker stops updating and the container becomes unhealthy while the main loop keeps retrying—by design.

To tune timing without rebuilding, override the health check in Compose, for example:

services:
  nextcloudclient:
    image: docker.asperti.com/paspo/nextcloudclient
    healthcheck:
      interval: 2m
      start_period: 180s

Notes

• If you're using 2FA in nextcloud, please create an application-specific password.
• It's very important to set correct UID & GID when running for an unprivileged user