README
¶
Wallpapers
A site that displays Nat Welch's personal wallpaper collection. Images live in Google Cloud Storage, served via Imgix CDN. Metadata (dimensions, colors, tags) is stored in a local SQLite file (wallpapers.db) that ships with the container.
Architecture
| Component | Path | Purpose |
|---|---|---|
| Web server | cmd/server/ |
Serves the gallery and all HTML pages |
| Uploader | cmd/uploader/ |
Syncs Dropbox → GCS, analyzes new images |
| DB package | db/ |
GORM/SQLite models and queries |
| Analysis package | analysis/ |
Color extraction (k-means) + Gemini AI tagging |
Pages
| Route | Description |
|---|---|
/ |
Masonry gallery with search |
/image/{filename} |
Image detail (metadata, colors, keywords) |
/resolutions |
Browse all unique resolutions by count |
/colors |
18×18 HSL color grid showing match counts per cell |
/tags |
Browse all AI-extracted keywords sorted by count |
/search?q= |
JSON search API |
/all.json |
JSON dump of all images |
Search
- Keyword — matches against AI-extracted tags, filename, file format
- Color (
#rrggbb) — fuzzy match using RGB Euclidean distance (threshold ≈80), sorted closest-first - Resolution (
1920x1080) — fuzzy match within ±20% of each dimension, sorted closest-first
Image Pipeline (uploader)
- Walk
~/Dropbox/Photos/Wallpapers/DesktopWallpapers - Upload new/changed files to GCS (CRC32 deduplication)
- Analyze with Gemini (
gemini-2.5-flash): extract top-3 colors (k-means), resolution, and content tags - Store metadata in
wallpapers.db - Delete GCS files no longer present locally
Development
# Run the server (requires wallpapers.db in the working directory)
go run ./cmd/server
# or
task server
# Run tests
task test
# Run uploader (syncs Dropbox → GCS, needs GCP credentials)
task uploader
# Lint / format / vet
task check
Environment Variables
| Variable | Required | Description |
|---|---|---|
GEMINI_API_KEY |
Uploader only | Google Gemini API key for image analysis |
GOOGLE_APPLICATION_CREDENTIALS |
Uploader only | Path to GCP service account JSON |
PORT |
No | Server port (default: 8080) |
Deployment
Docker image builds both binaries from a single golang:1.26 stage and copies wallpapers.db into the final debian:bookworm-slim image. The container runs server by default on port 8080.
docker build -t wallpapers .
docker run -p 8080:8080 wallpapers
The uploader is a one-shot CLI run locally via update.sh (updates deps, syncs, commits the updated wallpapers.db).
Documentation
¶
Overview ¶
Package wallpapers provides helpers for managing wallpaper files stored in Google Cloud Storage, including CRC checksums, URL generation, and metadata.
Index ¶
- Constants
- Variables
- func DeleteFile(ctx context.Context, filename string) error
- func FormatName(in string) string
- func FullRezURL(key string) string
- func GetFileCRC(content []byte) uint32
- func GetGoogleCRC(ctx context.Context, filename string) (uint32, error)
- func RawURL(key string) string
- func ThumbURL(key string) string
- func UploadFile(ctx context.Context, filename string, content []byte) error
- type File
Constants ¶
const (
Bucket = "iccowalls"
)
Bucket is the GCS bucket name where wallpaper files are stored.
Variables ¶
var (
NameRegex = regexp.MustCompile("[^a-z0-9]")
)
NameRegex matches characters that are not allowed in normalized wallpaper file names.
Functions ¶
func DeleteFile ¶
DeleteFile removes the named object from the wallpaper GCS bucket.
func FormatName ¶
FormatName formats a filename to match our requirements.
func FullRezURL ¶
FullRezURL returns the URL a cropped version hosted by imgix.
func GetFileCRC ¶
GetFileCRC computes the CRC32C (Castagnoli) checksum of the given content.
func GetGoogleCRC ¶
GetGoogleCRC returns the CRC32C checksum that GCS has stored for the given object. If the object does not exist, it returns 0 with a nil error.
Types ¶
type File ¶
type File struct {
CRC32C uint32 `json:"-"`
Etag string `json:"etag"`
FileURL string `json:"-"`
FullRezURL string `json:"cdn"`
Name string `json:"key"`
Size int64 `json:"-"`
ThumbnailURL string `json:"thumbnail"`
Created time.Time `json:"created_at"`
Updated time.Time `json:"updated_at"`
}
File is a subset of storage.ObjectAttrs that we need.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package analysis provides image analysis functionality including color extraction, resolution detection, and Gemini API integration.
|
Package analysis provides image analysis functionality including color extraction, resolution detection, and Gemini API integration. |
|
cmd
|
|
|
server
command
Command server runs the wallpapers HTTP service: it serves the web UI, JSON API, and metrics endpoint backed by the wallpapers SQLite database.
|
Command server runs the wallpapers HTTP service: it serves the web UI, JSON API, and metrics endpoint backed by the wallpapers SQLite database. |
|
server/static
Package static embeds the HTML templates, CSS, and other static assets served by the wallpapers HTTP server.
|
Package static embeds the HTML templates, CSS, and other static assets served by the wallpapers HTTP server. |
|
uploader
command
Command uploader walks the local Dropbox wallpapers folder, normalizes filenames, upscales small images, uploads new/changed files to GCS, and records image metadata in the wallpapers database.
|
Command uploader walks the local Dropbox wallpapers folder, normalizes filenames, upscales small images, uploads new/changed files to GCS, and records image metadata in the wallpapers database. |
|
Package db provides SQLite database operations for image metadata.
|
Package db provides SQLite database operations for image metadata. |