Configuration

PicFast supports two config modes: config.yaml or PICFAST_ prefixed environment variables. Env vars always take precedence over YAML values.

Full example (config.yaml)

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
  allow_oauth_registration: true
  allow_user_image_processing: true
  skip_image_processing: false
  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: "{}"

Reference

database

Key	Env Variable	Type	Default	Description
`url`	`PICFAST_DATABASE_URL`	string	—	PostgreSQL connection string (required)

server

Key	Env Variable	Type	Default	Description
`port`	`PICFAST_SERVER_PORT`	int	8080	HTTP port to listen on
`base_url`	`PICFAST_SERVER_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`	`PICFAST_SERVER_WEB_DIR`	string	""	Path to frontend dist (optional; auto-detects `web-dist/` and `web/dist/`)
`pprof_enabled`	`PICFAST_SERVER_PPROF_ENABLED`	bool	false	Enable Go pprof endpoints at `/api/v1/admin/debug/pprof/*` (admin only)

storage

Key	Env Variable	Type	Default	Description
`local_root`	`PICFAST_STORAGE_LOCAL_ROOT`	string	"./data/uploads"	Root directory for file storage when using the local backend
`thumbnail_dir`	`PICFAST_STORAGE_THUMBNAIL_DIR`	string	"./data/thumbnails"	Directory for generated thumbnail files

jwt

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

app

Key	Env Variable	Type	Default	Description
`name`	`PICFAST_APP_NAME`	string	PicFast	Site name shown in page titles, emails, and the web UI
`web_base_url`	`PICFAST_APP_WEB_BASE_URL`	string	""	Frontend URL users land on after login. Falls back to `server.base_url` when empty. Required when OAuth is enabled.
`site_description`	`PICFAST_APP_SITE_DESCRIPTION`	string	""	Meta description for the web UI
`favicon_url`	`PICFAST_APP_FAVICON_URL`	string	""	Custom site favicon URL; empty uses the bundled favicon
`allow_guest_upload`	`PICFAST_APP_ALLOW_GUEST_UPLOAD`	bool	false	Allow uploading without an account
`guest_capacity_bytes`	`PICFAST_APP_GUEST_CAPACITY_BYTES`	int64	10737418240	Total storage quota shared across all guest uploads (10 GB)
`allow_registration`	`PICFAST_APP_ALLOW_REGISTRATION`	bool	false	Allow new user sign-ups. Set to false once you have your accounts.
`allow_oauth_registration`	`PICFAST_APP_ALLOW_OAUTH_REGISTRATION`	bool	false	Allow new accounts through OAuth/OIDC login. When email registration is disabled but this is enabled, the login page shows only OAuth sign-in options.
`allow_user_image_processing`	`PICFAST_APP_ALLOW_USER_IMAGE_PROCESSING`	bool	true	Allow users to opt into per-image compression / watermarking
`skip_image_processing`	`PICFAST_APP_SKIP_IMAGE_PROCESSING`	bool	false	Skip all image processing and store original files as-is. When enabled, user image processing settings are hidden and ignored.
`max_upload_bytes`	`PICFAST_APP_MAX_UPLOAD_BYTES`	int64	52428800	Default per-file upload limit in bytes (50 MB). Group-level limits can override this.
`require_email_verification`	`PICFAST_APP_REQUIRE_EMAIL_VERIFICATION`	bool	false	Require email verification before login. Only takes effect when SMTP is configured and reachable.
`audit_upload_logs`	`PICFAST_APP_AUDIT_UPLOAD_LOGS`	bool	false	Log all upload events to the audit log table
`user_initial_capacity`	`PICFAST_APP_USER_INITIAL_CAPACITY`	int64	524288000	Default storage quota per user in bytes (500 MB)
`default_image_ttl`	`PICFAST_APP_DEFAULT_IMAGE_TTL`	duration	0 (never)	Default expiry for uploaded images (0 = never, e.g. `24h`, `168h`)
`guest_image_ttl`	`PICFAST_APP_GUEST_IMAGE_TTL`	duration	0 (never)	Separate expiry for guest uploads (0 = use `default_image_ttl`)
`admin_email`	`PICFAST_APP_ADMIN_EMAIL`	string	""	If set with `admin_password`, auto-creates admin and skips the setup wizard
`admin_password`	`PICFAST_APP_ADMIN_PASSWORD`	string	""	Password for the auto-created admin account
`moderation_mode`	`PICFAST_APP_MODERATION_MODE`	string	disabled	`"disabled"` (default), `"manual"` (admin approval queue)
`footer_text_1`	`PICFAST_APP_FOOTER_TEXT_1`	string	""	Optional footer text line 1; hidden if empty
`footer_link_1`	`PICFAST_APP_FOOTER_LINK_1`	string	""	Optional link for footer text line 1
`footer_text_2`	`PICFAST_APP_FOOTER_TEXT_2`	string	""	Optional footer text line 2; hidden if empty
`footer_link_2`	`PICFAST_APP_FOOTER_LINK_2`	string	""	Optional link for footer text line 2
`icp_number`	`PICFAST_APP_ICP_NUMBER`	string	""	Chinese ICP filing number for sites hosted in China
`icp_link`	`PICFAST_APP_ICP_LINK`	string	https://beian.miit.gov.cn/	ICP filing link target
`psb_number`	`PICFAST_APP_PSB_NUMBER`	string	""	Chinese PSB filing number
`psb_link`	`PICFAST_APP_PSB_LINK`	string	""	PSB filing link target
`theme_config`	`PICFAST_APP_THEME_CONFIG`	json	""	Theme overrides as JSON (logo, colors, etc.)
`default_copy_format`	`PICFAST_APP_DEFAULT_COPY_FORMAT`	string	"markdown"	Format pre-selected on the upload page: `url`, `markdown`, `html`, `bbcode`
`copy_template`	`PICFAST_APP_COPY_TEMPLATE`	string	""	Optional custom template for the copied string (e.g. `![image]({url})`)
`analytics_provider`	`PICFAST_APP_ANALYTICS_PROVIDER`	string	""	"" (disabled), `"plausible"`, `"umami"`, `"ga4"`, `"baidu"`, `"custom"`
`analytics_config`	`PICFAST_APP_ANALYTICS_CONFIG`	json	""	Provider-specific config (see Analytics section)

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)

oauth

Key	Env Variable	Type	Description
`providers`	`PICFAST_OAUTH_PROVIDERS`	array	List of OAuth / OIDC providers. See the OAuth docs for setup guides.
`providers[].id`	—	string	Unique provider identifier (e.g. `"github"`, `"keycloak"`)
`providers[].display_name`	—	string	Name shown on the login button
`providers[].type`	—	string	`"oidc"` or `"github"`
`providers[].client_id`	—	string	OAuth client ID from the provider
`providers[].client_secret`	—	string	OAuth client secret from the provider
`providers[].issuer`	—	string	Required for `type: oidc`. OIDC issuer URL; used to validate the ID token's `iss` claim and (by default) to discover endpoints.
`providers[].auth_url`	—	string	OAuth authorization endpoint. Required when the provider doesn't support discovery, alongside `token_url` and `jwks_url`.
`providers[].token_url`	—	string	OAuth token endpoint. Required alongside `auth_url` when discovery is unavailable.
`providers[].userinfo_url`	—	string	OIDC userinfo endpoint. Optional; overrides the discovered or default endpoint in any mode.
`providers[].scopes`	—	[]string	OAuth scopes. Defaults to `[openid, profile, email]`
`providers[].jwks_url`	—	string	JWKS endpoint for ID token verification. Auto-discovered from `issuer` if unset.
`providers[].enabled`	—	bool	Enable this provider

mail

Key	Env Variable	Type	Default	Description
`host`	`PICFAST_MAIL_HOST`	string	""	SMTP server hostname
`port`	`PICFAST_MAIL_PORT`	int	1025	SMTP port (587 for STARTTLS, 465 for TLS, 1025 for local Mailpit)
`username`	`PICFAST_MAIL_USERNAME`	string	""	SMTP username
`password`	`PICFAST_MAIL_PASSWORD`	string	""	SMTP password
`encryption`	`PICFAST_MAIL_ENCRYPTION`	string	none	`"starttls"`, `"tls"`, or `"none"`
`from_email`	`PICFAST_MAIL_FROM_EMAIL`	string	noreply@picfast.local	Sender address; must be set when SMTP is configured
`from_name`	`PICFAST_MAIL_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.