O2/Movistar Cloud WebDAV Gateway

A Docker-first, Linux-native gateway that exposes O2 Cloud and Movistar Cloud (Telefónica personal cloud storage services) as a standard WebDAV share, plus a small web admin panel for authentication and status.

Point any WebDAV client — Finder, Windows Explorer, rclone, Nautilus, mobile apps — at the gateway and browse, upload, download, move, delete and lock your O2/Movistar Cloud files as if they were a normal network drive. The gateway handles each provider's session cookies, validation keys, upload/download quirks and metadata caching behind the scenes.

WebDAV endpoint: /dav
Admin panel: /admin
Interactive O2/Movistar login: a real Chromium session running inside the container, streamed to your browser over noVNC (default port 6080).

How it works

WebDAV client ──HTTP──> :8088 /dav ─┐
                                    ├─> o2gateway (FastAPI / ASGI) ─> O2/Movistar Cloud API
Browser ──────HTTP──> :8088 /admin ─┘         │
Browser ──────HTTP──> :6080 noVNC ────────────┘ (interactive login only)

The gateway is a single FastAPI/ASGI application (served by Uvicorn) that:

Serves a WebDAV router at /dav (PROPFIND, GET, PUT, DELETE, MKCOL, MOVE, COPY, LOCK/UNLOCK) backed by a pluggable cloud provider.
Serves an admin panel at /admin for O2/Movistar login, session status and logout.
Translates WebDAV operations into O2/Movistar Cloud API calls, caching metadata in a local SQLite database to keep listings fast.
Stores the selected provider's session (cookies + validation key) encrypted on disk.

The container also runs a headless X server (Xvfb) + fluxbox + x11vnc + websockify/noVNC so the interactive Chromium login can be driven from your own browser — see below.

Requirements

Docker and Docker Compose (the supported path — bundles Chromium, Playwright and the VNC stack).
A modern browser to reach /admin and the noVNC login screen.
An O2 Cloud or Movistar Cloud account (unless you only run the simulated provider).

For local (non-Docker) development you need Python 3.12+.

Quick start (Docker)

# 1. Configuration
cp .env.example .env

# 2. Create host directories mounted into the container
mkdir -p secrets config cache data

# 3. Create the secret files (see the Secrets section)
printf 'change-me-webdav\n' > secrets/webdav_password.txt
printf 'change-me-admin\n'  > secrets/admin_password.txt
openssl rand -base64 32     > secrets/app_encryption_key.txt

# 4. Start
docker compose up -d

By default docker-compose.yml pulls the prebuilt image garanda21/o2cloud_gateway_webdav:latest from Docker Hub — no local build needed. To build from source instead, replace the image: line with build: . and run docker compose up --build.

Then open:

Admin panel: http://localhost:8088/admin
WebDAV root: http://localhost:8088/dav

The shipped docker-compose.yml sets CLOUD_PROVIDER=o2. Set CLOUD_PROVIDER=movistar to use Movistar Cloud, or CLOUD_PROVIDER=simulated to try the gateway without an account (see Simulated mode).

Log in to the admin panel with ADMIN_USERNAME / the admin password, then authenticate to the selected cloud provider.

Logging in to O2/Movistar (interactive VNC login)

O2 Cloud and Movistar Cloud have no public API token flow, so the gateway logs in the same way a human does: it drives a real Chromium browser inside the container using Playwright, and lets you complete the selected provider's login form (including any 2FA / captcha / consent screens) with your own eyes and hands.

Because the container has no physical display, that Chromium instance runs on a virtual X server (Xvfb on DISPLAY=:99) and is exposed to you as a web-based VNC session:

Xvfb (:99)  ──>  Chromium (Playwright)  ──>  x11vnc  ──>  websockify + noVNC  ──>  your browser :6080

Flow:

Open the admin panel at /admin and start Assisted O2/Movistar login. This calls POST /api/admin/o2/login, which launches Chromium on the virtual display and navigates to O2_LOGIN_URL.
The panel shows (or links to) the noVNC screen. By default that is http://localhost:6080/vnc.html?autoconnect=true&resize=scale&reconnect=true (host/port derived from APP_BASE_URL + NOVNC_PORT, or overridden with O2_LOGIN_NOVNC_URL).
Complete the provider login in the VNC window — type your credentials, pass any 2FA/captcha, accept consent dialogs.
Once you land on the logged-in cloud page, the gateway captures the session cookies and provider validationKey. If that login flow exposes a renewable OAuth bundle and device identity, those are captured too. The resulting session is encrypted at O2_SESSION_FILE and Chromium is then closed.
Use Session status / test / logout in the admin panel to verify or clear the session.

The Chromium profile is persisted under /config/playwright-o2-profile/<provider> so a later assisted login can reuse the provider session. An explicit logout from the admin panel removes both the encrypted gateway session and this browser profile.

Automatic session renewal

The gateway supports two renewal paths:

If a 401 response contains a rotated OAuth bundle and JSESSIONID, the gateway performs POST /sapi/login/oauth, stores the new validationKey and retries the original operation once.
Web logins normally expose only cookies and validationKey. In that case the gateway reopens the persisted Chromium profile headlessly, reuses its SSO session and captures a fresh provider session without showing noVNC.

Sessions are also kept active preventively before the provider's idle window expires. The gateway makes a lightweight authenticated API request every 5 minutes by default. Set O2_SESSION_KEEPALIVE_SECONDS=0 to disable this behavior.

Concurrent WebDAV requests share a single renewal, avoiding parallel token rotation or multiple Chromium processes. Human intervention is required only when both the API credentials and the persisted browser SSO session have expired.

Notes:

O2_PLAYWRIGHT_HEADLESS=false is required for the interactive flow — the browser must be rendered so you can see and drive it over VNC. Setting it to true disables the visible session.
The bundled x11vnc runs with -nopw (no VNC password) and is intended to be reached only over your own trusted network / port mapping. Do not expose port 6080 to the public internet.

Manual session import

If you cannot use the VNC flow (headless host, restricted network), you can import a session captured elsewhere. Provide the same JSON shape the gateway stores for the selected provider:

{
  "validationKey": "...",
  "cookies": [
    {"name": "...", "value": "...", "domain": "<provider-host>", "path": "/"}
  ],
  "userAgent": "Mozilla/5.0 ...",
  "oauthBundle": "...",
  "deviceId": "...",
  "deviceName": "...",
  "encryptionToken": "...",
  "createdAt": "2026-07-04T12:00:00Z"
}

Import it through the admin panel's manual import action (or place it at O2_SESSION_FILE). The gateway validates and encrypts it the same way as the assisted flow.

Legacy imports containing only cookies and validationKey remain compatible. They can renew silently only when the gateway also has a persistent browser profile created by an assisted login; a standalone JSON import has no browser SSO session to reuse.

Using the WebDAV share

Authenticate with WEBDAV_USERNAME and the WebDAV password.

macOS (Finder): Go → Connect to Server → http://localhost:8088/dav
Windows: Map network drive → http://localhost:8088/dav

rclone:

rclone config create cloud webdav \
  url=http://localhost:8088/dav vendor=other \
  user=webdav-user pass="$(rclone obscure change-me-webdav)"
rclone ls cloud:

Set WEBDAV_READ_ONLY=true to block all writes (PUT/DELETE/MOVE/MKCOL). LOCK support is implemented for clients that require it (macOS Finder, Office).

Simulated mode (no real cloud account)

Set CLOUD_PROVIDER=simulated to run the whole WebDAV/admin stack against a fake in-container filesystem rooted at SIMULATED_ROOT (default /data/simulated). No O2/Movistar login is needed. Useful for testing WebDAV clients and the gateway itself.

Secrets

Sensitive values are read from files (Docker secrets), not inline env vars where possible. Each *_FILE variable points at a file whose contents are the secret; the corresponding non-file variable (if set) takes precedence.

File (host)	Mounted as	Purpose
`secrets/webdav_password.txt`	`/run/secrets/webdav_password`	WebDAV client password (`WEBDAV_PASSWORD_FILE`)
`secrets/admin_password.txt`	`/run/secrets/admin_password`	Admin panel password (`ADMIN_PASSWORD_FILE`)
`secrets/app_encryption_key.txt`	`/run/secrets/app_encryption_key`	Encrypts the stored provider session and signs admin sessions (`APP_ENCRYPTION_KEY_FILE`, `ADMIN_SESSION_SECRET_FILE`)

Generate the encryption key with openssl rand -base64 32. Keep these files out of version control (secrets/ should be git-ignored).

Environment variables

All settings come from environment variables (or .env). Defaults below are the in-code defaults; docker-compose.yml overrides several of them.

Application

Variable	Default	Description
`APP_HOST`	`0.0.0.0`	Interface the ASGI server binds to inside the container.
`APP_PORT`	`8080`	Port the app listens on inside the container (mapped to `8088` on the host by compose).
`APP_BASE_URL`	`http://localhost:8080`	Public base URL of the gateway. Used to build absolute links, including the default noVNC URL.
`APP_ENCRYPTION_KEY_FILE`	(unset)	File containing the encryption key used to encrypt the stored O2/Movistar session.
`PUID`	`10001`	Host user id the container runs as. Set to the owner of the mounted volumes so the app can write `/config`, `/cache`, `/data`.
`PGID`	`10001`	Host group id the container runs as (see `PUID`).

The container starts as root only to apply PUID/PGID, fix volume ownership and prepare the X11 socket, then drops privileges via gosu. No user: override or HOME variable is needed in compose.

Cloud provider

Variable	Default	Description
`CLOUD_PROVIDER`	`simulated`	Backend to serve: `o2` (O2 Cloud), `movistar` (Movistar Cloud), or `simulated` (fake local filesystem).
`SIMULATED_ROOT`	`/data/simulated`	Root directory for the simulated provider's fake files.