README
¶
AltMount
A WebDAV server backed by NZB/Usenet that provides seamless access to Usenet content through standard WebDAV protocols.
📖 Documentation
Complete setup guides, configuration options, API reference, and troubleshooting information.
Quick Start
Docker (Recommended)
services:
altmount:
extra_hosts:
- "host.docker.internal:host-gateway" # Optional if you rclone is outside the container
image: ghcr.io/kipsilabs/altmount:latest
container_name: altmount
environment:
- PUID=1000
- PGID=1000
- PORT=8080
- JWT_SECRET=change-me-to-a-strong-random-secret # Required when login is enabled (auth.login_required: true)
- COOKIE_DOMAIN=localhost # Must match the domain/IP where web interface is accessed
volumes:
- ./config:/config
- /mnt:/mnt:rshared
- /metadata:/metadata # This is optional you can still use /mnt
- /var/run/docker.sock:/var/run/docker.sock # Required for the auto-update feature
group_add:
- "999" # GID of the docker group on the host (run `getent group docker | cut -d: -f3` to find yours)
ports:
- "8080:8080"
restart: unless-stopped
devices:
- /dev/fuse:/dev/fuse:rwm
cap_add:
- SYS_ADMIN
security_opt:
- apparmor:unconfined
CLI Installation
go install github.com/kipsilabs/altmount@latest
altmount serve --config config.yaml
Windows: Enable Long Path Support
The Windows AltMount binaries are built with a long-path-aware manifest, which
opts the process in to paths longer than the legacy MAX_PATH (260 character)
limit. However, Windows also requires the matching system-wide setting to be
enabled before long paths actually work — without it, you may see errors like
The filename or extension is too long when accessing deeply nested releases.
Enable it once per machine in an elevated PowerShell prompt (Run as administrator), then restart AltMount:
New-ItemProperty `
-Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" `
-Value 1 `
-PropertyType DWORD `
-Force
Equivalent via Group Policy: Computer Configuration → Administrative Templates → System → Filesystem → Enable Win32 long paths.
This setting requires Windows 10 version 1607 (build 14393) or newer. A reboot is not strictly required, but any already-running process — including AltMount and your file manager — needs to be restarted to pick up the change.
Links
- 📚 Documentation
- 🐛 Issues
- 💬 Discussions
- 🎮 Discord
Contributing
See the Development Guide. Development/setup for information on setting up a development environment and contributing to the project.
License
This project is licensed under the terms specified in the LICENSE file.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
altmount
command
|
|
|
internal
|
|
|
api
Package api provides the AltMount REST API.
|
Package api provides the AltMount REST API. |
|
arrs/failures
Package failures holds the in-memory per-target failure counts behind the arrs circuit breaker (arrs.queue_cleanup_max_failures).
|
Package failures holds the in-memory per-target failure counts behind the arrs circuit breaker (arrs.queue_cleanup_max_failures). |
|
encryption/rclone/pkcs7
Package pkcs7 implements PKCS#7 padding
|
Package pkcs7 implements PKCS#7 padding |
|
errors
Package errors provides shared error types used across multiple packages.
|
Package errors provides shared error types used across multiple packages. |
|
holes
Package holes is the shared model + threshold policy for "holes": runs of consecutive segments confirmed missing from Usenet providers.
|
Package holes is the shared model + threshold policy for "holes": runs of consecutive segments confirmed missing from Usenet providers. |
|
httpclient
Package httpclient provides a centralized HTTP client factory with preset configurations.
|
Package httpclient provides a centralized HTTP client factory with preset configurations. |
|
importer
Package importer provides import queue processing for NZB files.
|
Package importer provides import queue processing for NZB files. |
|
importer/postprocessor
Package postprocessor handles all post-import processing steps including symlink creation, STRM file generation, VFS notifications, health check scheduling, and ARR notifications.
|
Package postprocessor handles all post-import processing steps including symlink creation, STRM file generation, VFS notifications, health check scheduling, and ARR notifications. |
|
importer/queue
Package queue provides queue management for the NZB import service.
|
Package queue provides queue management for the NZB import service. |
|
importer/rarname
Package rarname holds the pure RAR / split-volume filename parsing used across the importer.
|
Package rarname holds the pure RAR / split-volume filename parsing used across the importer. |
|
importer/scanner
Package scanner provides directory scanning and NZBDav import functionality.
|
Package scanner provides directory scanning and NZBDav import functionality. |
|
nzbfile
Package nzbfile centralizes on-disk NZB I/O, hiding gzip compression so callers always deal with plain XML regardless of how the file is stored.
|
Package nzbfile centralizes on-disk NZB I/O, hiding gzip compression so callers always deal with plain XML regardless of how the file is stored. |
|
nzbfilesystem/segcache
Package segcache provides a segment-aligned disk cache for Usenet file data.
|
Package segcache provides a segment-aligned disk cache for Usenet file data. |
|
par2repair
Package par2repair reconstructs missing usenet articles from a release's PAR2 recovery data, streaming the recovery set from NNTP and persisting repaired article payloads to a local patch store.
|
Package par2repair reconstructs missing usenet articles from a release's PAR2 recovery data, streaming the recovery set from NNTP and persisting repaired article payloads to a local patch store. |
|
regexcache
Package regexcache provides a process-wide, size-bounded cache of compiled regular expressions.
|
Package regexcache provides a process-wide, size-bounded cache of compiled regular expressions. |
|
streambench
Package streambench holds the result schema, statistics helpers and the regression comparison used by the streaming benchmarks in internal/nzbfilesystem and by cmd/compare.
|
Package streambench holds the result schema, statistics helpers and the regression comparison used by the streaming benchmarks in internal/nzbfilesystem and by cmd/compare. |
|
streambench/cmd/compare
command
Command compare diffs two streaming benchmark result files and exits 1 when any metric regressed past the threshold.
|
Command compare diffs two streaming benchmark result files and exits 1 when any metric regressed past the threshold. |
|
testsupport/fakepool
Package fakepool provides a deterministic in-process replacement for nntppool.Client used by tests that exercise AltMount's streaming and connection-management invariants.
|
Package fakepool provides a deterministic in-process replacement for nntppool.Client used by tests that exercise AltMount's streaming and connection-management invariants. |
|
testsupport/goroutines
Package goroutines provides a small helper for tests that need to assert goroutine leaks — specifically, the closeWg accumulation scenarios in the streaming pipeline where rapid seek/close cycles can spawn background goroutines that outlive the request.
|
Package goroutines provides a small helper for tests that need to assert goroutine leaks — specifically, the closeWg accumulation scenarios in the streaming pipeline where rapid seek/close cycles can spawn background goroutines that outlive the request. |
|
testsupport/nntpserver
Package nntpserver provides an in-process NNTP server that speaks enough of the wire protocol for a real *nntppool.Client to connect, authenticate, pipeline commands, and fetch yEnc article bodies.
|
Package nntpserver provides an in-process NNTP server that speaks enough of the wire protocol for a real *nntppool.Client to connect, authenticate, pipeline commands, and fetch yEnc article bodies. |
|
testsupport/nzbbuild
Package nzbbuild provides helpers for constructing NZB objects and writing them to temporary files in tests.
|
Package nzbbuild provides helpers for constructing NZB objects and writing them to temporary files in tests. |
|
testsupport/par2gen
Package par2gen builds minimal valid PAR2 index files in memory for use in tests that exercise PAR2-based filename deobfuscation.
|
Package par2gen builds minimal valid PAR2 index files in memory for use in tests that exercise PAR2-based filename deobfuscation. |
|
testsupport/segments
Package segments builds deterministic segment payloads and identifiers for use by streaming/connection tests.
|
Package segments builds deterministic segment payloads and identifiers for use by streaming/connection tests. |
|
updater
Package updater provides binary self-update capabilities for standalone (non-Docker) installs of altmount.
|
Package updater provides binary self-update capabilities for standalone (non-Docker) installs of altmount. |
|
pkg
|
|
Click to show internal directories.
Click to hide internal directories.