Configuration

PicFast supports two config modes: config.yaml or environment variables. Environment variables always take precedence over YAML values.

Full example

server:
  port: 8080
  base_url: "http://localhost:8080"
  web_dir: ""
  pprof_enabled: false

database:
  url: "postgres://picfast:picfast@localhost:5432/picfast?sslmode=disable"

jwt:
  secret: "change-me-in-production"
  access_ttl: 15m
  refresh_ttl: 168h
  signing_method: "HS256"

storage:
  local_root: "./data/uploads"
  thumbnail_dir: "./data/thumbnails"

mail:
  host: "127.0.0.1"
  port: 1025
  username: ""
  password: ""
  from_email: "noreply@picfast.local"
  from_name: "PicFast"
  encryption: "none"

app:
  name: "PicFast"
  site_description: "PicFast is a modern self-hosted image hosting service."
  favicon_url: ""
  allow_guest_upload: false
  allow_registration: true
  require_email_verification: true
  audit_upload_logs: false
  user_initial_capacity: 524288000
  guest_capacity_bytes: 10737418240
  default_image_ttl: "0"
  guest_image_ttl: "0"
  admin_email: ""
  admin_password: ""
  moderation_mode: "disabled"
  footer_text_1: ""
  footer_link_1: ""
  footer_text_2: ""
  footer_link_2: ""
  icp_number: ""
  icp_link: "https://beian.miit.gov.cn/"
  psb_number: ""
  psb_link: ""
  analytics_provider: ""
  analytics_config: "{}"

Defaults

Only values that differ from defaults or are commonly overridden are shown in the reference tables below.

server

Key	Type	Default	Description
`port`	int	8080	HTTP port to listen on
`base_url`	string	http://localhost:8080	Public URL of the service. Must be set for email verification links and ShareX config to work correctly.
`web_dir`	string	""	Path to frontend dist for self-hosted frontend (optional; auto-detects `web-dist/` and `web/dist/`)
`pprof_enabled`	bool	false	Enable Go pprof endpoints at `/api/v1/admin/debug/pprof/*` (admin only)

jwt

Key	Type	Default	Description
`secret`	string	change-me-in-production	Required. Must be changed. Using the default value causes a startup error. Generate a strong random value in production.
`access_ttl`	duration	15m	Access token lifetime
`refresh_ttl`	duration	168h	Refresh token lifetime (7 days)
`signing_method`	string	HS256	HS256, HS384, or HS512

app

Key	Type	Default	Description
`name`	string	PicFast	Site name shown in page titles, emails, and the web UI
`site_description`	string	""	Meta description for the web UI
`favicon_url`	string	""	Custom site favicon URL; empty uses the bundled favicon
`allow_guest_upload`	bool	false	Allow uploading without an account
`guest_capacity_bytes`	int64	10737418240	Total storage quota shared across all guest uploads (10 GB)
`allow_registration`	bool	true	Allow new user sign-ups. Set to false once you have your accounts.
`require_email_verification`	bool	true	Require email verification before login. Only takes effect when `mail.*` is configured and the SMTP server is reachable.
`audit_upload_logs`	bool	false	Log all upload events to the audit log table
`user_initial_capacity`	int64	524288000	Default storage quota per user in bytes (500 MB)
`guest_capacity_bytes`	int64	10737418240	Total storage quota shared across all guest uploads (10 GB)
`default_image_ttl`	duration	0 (never)	Default expiry for uploaded images (0 = never expire, e.g. `24h`, `168h`)
`guest_image_ttl`	duration	0 (never)	Separate expiry for guest uploads (0 = use `default_image_ttl`, e.g. `24h` for shorter guest retention)
`admin_email`	string	""	If set with `admin_password`, auto-creates admin on first startup and skips the setup wizard
`admin_password`	string	""	Password for the auto-created admin account
`moderation_mode`	string	disabled	`"disabled"` (default), `"manual"` (admin approval queue)
`footer_text_1`	string	""	Optional footer text line 1; hidden if empty
`footer_link_1`	string	""	Optional link for footer text line 1
`footer_text_2`	string	""	Optional footer text line 2; hidden if empty
`footer_link_2`	string	""	Optional link for footer text line 2
`icp_number`	string	""	Chinese ICP filing number for sites hosted in China
`icp_link`	string	https://beian.miit.gov.cn/	ICP filing link target
`psb_number`	string	""	Chinese PSB filing number
`psb_link`	string	""	PSB filing link target
`analytics_provider`	string	""	"" (disabled), `"plausible"`, `"umami"`, `"ga4"`, `"baidu"`, `"custom"`
`analytics_config`	json	""	Provider-specific config (see Analytics section below)

Analytics providers

PicFast supports integrating with analytics services for visitor tracking on the web UI. Configure via app.analytics_provider and app.analytics_config.

Provider	Config fields
`plausible`	`domain` (required), `server_url` (optional)
`umami`	`website_id` (required), `script_url` (required)
`ga4`	`measurement_id` (required)
`baidu`	`site_id` (required)
`custom`	`script_html` (raw HTML/script string injected into every page)

mail

Key	Type	Default	Description
`host`	string	""	SMTP server hostname
`port`	int	1025	SMTP port (587 for STARTTLS, 465 for TLS, 1025 for local Mailpit)
`encryption`	string	none	`"starttls"`, `"tls"`, or `"none"`
`from_email`	string	noreply@picfast.local	Sender address; must be set when SMTP is configured
`from_name`	string	PicFast	Sender display name

Email verification notes

By default, registration succeeds immediately and the user can log in right away. To enable email verification:

Configure mail.* with a working SMTP server
Set app.require_email_verification = true

If require_email_verification is set but SMTP is unreachable, the system falls back to immediate registration and logs a warning at startup.

For local development, the included mailpit (ports 1025 SMTP / 8025 UI) captures all outgoing mail locally without sending to external addresses.