Repository Guidelines

Project Structure & Module Organization

Root contains
```
docker-compose.yml
```
,
```
.env
```
(local only), and helper scripts like
```
git_push.py
```
and
```
summarize_codebase.sh
```
.

All Homepage configuration lives under

config/

(e.g.,

bookmarks.*

services.*

settings.*

widgets.*

docker.*

Example files (
```
*.example
```
) are the templates you should edit and then copy to
```
*.yaml
```
for local use; YAML files and
```
.env
```
are intentionally git-ignored.

Build, Test, and Development Commands

```
docker compose up -d
```
— start or update the Dashboard stack in detached mode.
```
docker compose down
```
— stop and remove the stack (containers only).
```
docker compose logs homepage
```
— inspect the Homepage container logs for troubleshooting.
```
docker compose config
```
— validate the compose configuration before pushing.
```
./summarize_codebase.sh .
```
— optional helper to generate a local
```
codebase_summary.txt
```
(not committed).

Coding Style & Configuration Conventions

Prefer small, focused changes in
```
config/*.example
```
and keep
```
*.yaml
```
environment-specific.
YAML: two-space indentation, lowercase keys with hyphen-separated words where possible.
Python helpers use 4-space indentation and
```
snake_case
```
for functions; shell scripts follow existing style and use descriptive variable names.

Testing Guidelines

There is no automated test suite; rely on Docker commands for validation.
Before opening a PR, run
```
docker compose config
```
and bring the stack up locally with
```
docker compose up -d
```
to ensure it boots cleanly.
Manually verify the Dashboard UI loads and configured services/widgets appear as expected.

Commit & Pull Request Guidelines

Use short, descriptive, sentence-style commit messages (e.g.,
```
Update services example for NPM
```
,
```
Add new bank icon
```
).
Group related configuration and asset changes in a single commit; avoid mixing unrelated updates.
PRs should include: a concise summary, a brief description of config or icon changes, any relevant screenshots of the Dashboard, and notes on how you validated the stack.

Security & Secrets

Never commit real secrets or host-specific details;
```
.env
```
and
```
config/*.yaml
```
are local-only and must not be added to Git.
When sharing examples, sanitize domains, IPs, and tokens, and prefer updates to
```
*.example
```
files instead of real YAMLs.

Project Structure & Module Organization

Root contains

docker-compose.yml

.env

(local only), and helper scripts like

git_push.py

and

summarize_codebase.sh

All Homepage configuration lives under

config/

(e.g.,

bookmarks.*

services.*

settings.*

widgets.*

docker.*

Example files (

*.example

) are the templates you should edit and then copy to

*.yaml

for local use; YAML files and

.env

are intentionally git-ignored.

Build, Test, and Development Commands

docker compose up -d

— start or update the Dashboard stack in detached mode.

docker compose down

— stop and remove the stack (containers only).

docker compose logs homepage

— inspect the Homepage container logs for troubleshooting.

docker compose config

— validate the compose configuration before pushing.

./summarize_codebase.sh .

— optional helper to generate a local

codebase_summary.txt

(not committed).

Coding Style & Configuration Conventions

Prefer small, focused changes in

config/*.example

and keep

*.yaml

environment-specific.

YAML: two-space indentation, lowercase keys with hyphen-separated words where possible.

Python helpers use 4-space indentation and

snake_case

for functions; shell scripts follow existing style and use descriptive variable names.

Commit & Pull Request Guidelines

Use short, descriptive, sentence-style commit messages (e.g.,

Update services example for NPM

Add new bank icon

Group related configuration and asset changes in a single commit; avoid mixing unrelated updates.

PRs should include: a concise summary, a brief description of config or icon changes, any relevant screenshots of the Dashboard, and notes on how you validated the stack.

Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Configuration Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Secrets

Related Skills

Markdown Converter

Nano Banana Pro

1password

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Configuration Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Secrets