diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5ad90fc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# Homepage
+
+Self-hosted start page / dashboard using [Homepage](https://gethomepage.dev/) via Docker Compose.
+
+---
+
+## Repository Contents
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yaml` | Homepage service definition |
+
+Configuration files live outside this repo at `/etc/homepage/` on the host.
+
+---
+
+## Stack
+
+- **Homepage** - `ghcr.io/gethomepage/homepage:latest`
+- **Docker socket** - mounted for live container status widgets
+- **SMB share** - `/smb` mounted into the container for any assets served from network storage
+
+---
+
+## Prerequisites
+
+- Docker + Docker Compose installed
+- `/etc/homepage/` directory created on the host with your config files in place
+- `/etc/homepage/images/` directory created for custom images/icons
+- `/etc/homepage/.env` file created (see below)
+
+---
+
+## Setup
+
+### 1. Create the config directory
+
+```bash
+mkdir -p /etc/homepage/images
+```
+
+### 2. Create the `.env` file
+
+Homepage reads environment variables from `/etc/homepage/.env`. At minimum create an empty file so the container starts:
+
+```bash
+touch /etc/homepage/.env
+```
+
+API keys for service widgets go here. Example:
+
+```env
+HOMEPAGE_VAR_SONARR_KEY=your_sonarr_api_key
+HOMEPAGE_VAR_RADARR_KEY=your_radarr_api_key
+HOMEPAGE_VAR_TAUTULLI_KEY=your_tautulli_api_key
+```
+
+Variables prefixed with `HOMEPAGE_VAR_` are available in your `services.yaml` as `{{HOMEPAGE_VAR_SONARR_KEY}}`.
+
+### 3. Populate config files
+
+Homepage is configured entirely through YAML files in `/etc/homepage/`:
+
+| File | Purpose |
+|------|---------|
+| `settings.yaml` | Title, theme, color scheme, layout |
+| `services.yaml` | Service tiles and widgets |
+| `bookmarks.yaml` | Bookmark groups and links |
+| `widgets.yaml` | Top-bar info widgets (search, date, resources) |
+| `docker.yaml` | Docker socket integration config |
+| `custom.css` | Optional style overrides |
+| `custom.js` | Optional JS overrides |
+
+See the [Homepage docs](https://gethomepage.dev/configs/) for full reference.
+
+### 4. Start the stack
+
+```bash
+docker compose up -d
+```
+
+Homepage will be available at `http://<host>:3000`.
+
+---
+
+## Ports
+
+| Port (Host) | Port (Container) | Purpose |
+|-------------|------------------|---------|
+| `3000` | `3000` | Homepage web UI |
+
+---
+
+## Allowed Hosts
+
+The `HOMEPAGE_ALLOWED_HOSTS` environment variable restricts which hostnames/IPs can serve the dashboard. Currently set to:
+
+```
+10.10.14.199:3000 (host IP)
+home.wittenberger.us
+home.wittenberger.local
+```
+
+Add or remove entries as needed when accessing from additional addresses.
+
+---
+
+## Volumes
+
+| Host Path | Container Path | Purpose |
+|-----------|----------------|---------|
+| `/etc/homepage` | `/app/config` | All YAML config files and `.env` |
+| `/etc/homepage/images` | `/app/public/images` | Custom images and icons |
+| `/var/run/docker.sock` | `/var/run/docker.sock` | Docker integration (container status) |
+| `/smb` | `/smb` | SMB share mount for network assets |
+
+---
+
+## Docker Integration
+
+The Docker socket mount enables Homepage to display live container status on service tiles. Configure which containers to show in `/etc/homepage/docker.yaml` and reference them in `services.yaml` with a `docker` widget block.
+
+> The Docker socket grants full Docker API access to the container. If this is a concern, consider fronting it with [Docker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy) to restrict permissions.
+
+---
+
+## Updating
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Config files in `/etc/homepage/` are unaffected by updates.
\ No newline at end of file