The webserver component enables Viserons front-end interface.
It also provides the websocket and REST API.
The user interface can be reached by default on port 8888 inside the container.
note
webserver is always enabled, even if not present in the config.yaml
Public Image URLs
The webserver can generate public URLs for images (e.g., for notifications) that are accessible without authentication. These URLs can be configured with:
- Expiration time (
public_url_expiry_hours): How long the URL remains valid (default: 24 hours, max: 31 days) - Download limit (
public_url_max_downloads): How many times the image can be downloaded before automatic deletion0(default): Unlimited downloads - only time expiration applies1: Single-use URL - perfect for one-time notifications2+: Limited sharing - image deleted after N downloads
Use cases:
- Single-use notifications: Set
public_url_max_downloads: 1for images that should only be viewed once - Limited sharing: Set a specific number to allow multiple views but prevent unlimited distribution
- Temporary unlimited access: Set
public_url_max_downloads: 0with an expiry time for time-limited but unlimited views
Configuration
Configuration example
/config/config.yaml
webserver:
port: 8888
public_base_url: "https://public.dns-viseron.org"
public_url_expiry_hours: 240 # default: 24, max: 744 = 31 days
public_url_max_downloads: 3 # default: 0 (unlimited)
webservermap (optional)
Webserver configuration.
portinteger deprecated
DEPRECATED. Config option 'port' is deprecated and will be removed in a future version.
Port to run the webserver on.
Port to run the webserver on.
debugboolean (optional, default:
false)Enable debug mode for the webserver. WARNING: Dont have this enabled in production as it weakens security.
subpathstring (optional)
Subpath where the webserver is served from when behind a reverse proxy (e.g. '/viseron').
public_base_urlstring (optional)
Public base URL for Viseron (e.g., https://viseron.example.com). Used for generating public links accessible from outside your network.
public_url_expiry_hoursinteger (optional, default:
24)Number of hours before public image URLs expire (default: 24, max: 744 = 31 days).
public_url_max_downloadsinteger (optional, default:
0)Maximum number of times a public image URL can be downloaded before it is automatically deleted. Set to 0 for unlimited downloads (default: 0 = unlimited).
authmap (optional)
Authentication configuration.
session_expirymap (optional)
Session expiry time. After this time the user will be logged out. By default the sessions are infinite.
daysinteger (optional, default:
0)Days to expire session.
hoursinteger (optional, default:
0)Hours to expire session.
minutesinteger (optional, default:
0)Minutes to expire session.
rate_limitsmap (optional)
Per-IP rate limits applied to authentication endpoints. Tune these if you have many legitimate clients behind a single IP, or lower them to harden against brute force.
loginmap (optional)
Rate limit for the login endpoint (POST /api/v1/auth/login).
max_attemptsinteger (optional, default:
10)Maximum number of attempts allowed within the window.
window_secondsfloat (optional, default:
60)Length of the sliding window in seconds.
tokenmap (optional)
Rate limit for the token endpoint (POST /api/v1/auth/token), used to refresh access tokens.
max_attemptsinteger (optional, default:
30)Maximum number of attempts allowed within the window.
window_secondsfloat (optional, default:
60)Length of the sliding window in seconds.
onboardingmap (optional)
Rate limit for the initial onboarding endpoint (POST /api/v1/onboarding).
max_attemptsinteger (optional, default:
5)Maximum number of attempts allowed within the window.
window_secondsfloat (optional, default:
60)Length of the sliding window in seconds.
Troubleshooting
To enable debug logging for
webserver, add the following to your config.yaml/config/config.yaml
logger:
logs:
viseron.components.webserver: debug