HTTPS and Reverse Proxy

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• internal/app/app.go
• internal/config/config_test.go
• cmd/gocasa/main.go
• internal/app/ics.go
• internal/apptest/apptest.go

GoCasa serves plain HTTP content and relies on an external reverse proxy to provide TLS termination and HTTPS support. This architecture simplifies the GoCasa binary while enabling essential features that require a secure context, such as Google OAuth integration and specific browser APIs for Wall displays.

Sources: README.md:65-67, README.md:71-74

Architecture Overview

GoCasa listens on a local address (default :8080) and expects a reverse proxy to handle incoming HTTPS requests from clients. The application ignores X-Forwarded-* headers and instead determines its public identity using the BASE_URL environment variable.

Traffic Flow

The following diagram illustrates how a client request moves from the public internet or local network through the proxy to the GoCasa service.

The reverse proxy converts secure external traffic into plain internal traffic for the application.
Sources: README.md:21, README.md:66-68, cmd/gocasa/main.go:94-98

Configuration and Base URL

The BASE_URL variable is the primary driver for GoCasa's network identity. It must be set to the full https:// address that users enter in their browsers.

Variable	Description	Impact
BASE_URL	The public URL (e.g., https://casa.example.com)	Drives Secure cookies, Google OAuth redirects, absolute ICS links, and CSRF protection.
ADDR	The internal listen address (default :8080)	Defines where the GoCasa binary binds its HTTP server.

Sources: README.md:23-24, internal/config/config_test.go:17, internal/app/app.go:102-105

Cross-Origin Protection

GoCasa implements native cross-origin protection. It validates the Sec-Fetch-Site and Origin headers against the scheme and host defined in BASE_URL. If a request does not match the trusted origin, the application refuses unsafe cross-site requests.

csrf := http.NewCrossOriginProtection()
if err := csrf.AddTrustedOrigin(a.Config.BaseURL.Scheme + "://" + a.Config.BaseURL.Host); err != nil {
    panic(err) // BASE_URL is validated by config.Load
}
return csrf.Handler(a.withUnlock(mux))

Sources: internal/app/app.go:102-107, internal/apptest/apptest.go:111-120

Functional Requirements for HTTPS

While GoCasa operates over plain HTTP, several critical features are disabled or non-functional unless accessed via HTTPS:

• Google Integration: Google requires an https redirect URI for OAuth. Connection to Google accounts will fail without HTTPS.
• Secure Cookies: The application uses BASE_URL to determine if session cookies should be flagged as Secure.
• Browser APIs: Modern browsers restrict the following features to "Secure Contexts":
  • Screen Wake Lock: Used by Wall displays to keep the screen active.
  • Camera Motion-Wake: Used to wake the screen when movement is detected.

Sources: README.md:24, README.md:71-74

Implementation Recipe

To enable HTTPS, you must configure a local DNS entry and a reverse proxy with valid certificates.

1. DNS Configuration

Point your chosen domain (e.g., casa.example.com) to the internal LAN IP of the GoCasa host. This can be done via a router, Pi-hole, or AdGuard. The domain does not need to be publicly resolvable.
Sources: README.md:77-80

2. Reverse Proxy Setup (e.g., Nginx Proxy Manager)

1. SSL Certificate: Obtain a certificate for the domain. Using Let's Encrypt with a DNS-01 challenge is recommended as it does not require opening ports to the internet.
2. Proxy Host: Create a host for the domain, setting the scheme to http and the forward port to 8080.
3. Force SSL: Enable "Force SSL" in the proxy configuration to ensure all traffic is encrypted.

Sources: README.md:81-89

3. Application Updates

Set the environment variable BASE_URL=https://<your-domain> and restart the GoCasa container. The application will use this URL to generate absolute links for features like ICS exports.

func (a *App) icsURL() string { 
    return a.Config.BaseURL.JoinPath("calendar.ics").String() 
}

Sources: README.md:90-91, internal/app/ics.go:16

Security and Remote Access

GoCasa is designed for home network usage. Reaching the application from outside the home network requires a separate solution such as a VPN, a tunnel, or an authenticating proxy. The application does not provide built-in authentication for remote access; it relies on the environment or reverse proxy to handle such requirements.
Sources: README.md:95-97

Summary

GoCasa maintains a simple HTTP internal server and delegates all encryption responsibilities to a reverse proxy. This requires the BASE_URL to be accurately configured with an https scheme to enable Google integrations, secure session handling, and advanced browser features for Wall displays.
Sources: README.md:65-68, README.md:71-74