From f0a15c55b4b0bd513f39c31c30e4b4b6e93b5b61 Mon Sep 17 00:00:00 2001 From: VishnuByrraju Date: Tue, 14 Apr 2026 19:36:51 +0530 Subject: [PATCH 1/4] docs: add Retype documentation site --- .github/workflows/docs.yml | 45 +++++ docs/.gitignore | 1 + docs/api/index.md | 278 +++++++++++++++++++++++++++ docs/community/contributing.md | 191 ++++++++++++++++++ docs/community/index.md | 32 +++ docs/community/widgets.md | 204 ++++++++++++++++++++ docs/configuration/appearance.md | 84 ++++++++ docs/configuration/dashboard.md | 138 +++++++++++++ docs/configuration/index.md | 10 + docs/features/docker.md | 100 ++++++++++ docs/features/forward-auth.md | 127 ++++++++++++ docs/features/index.md | 10 + docs/features/monitoring.md | 89 +++++++++ docs/features/sso.md | 155 +++++++++++++++ docs/getting-started/index.md | 10 + docs/getting-started/installation.md | 205 ++++++++++++++++++++ docs/index.md | 128 ++++++++++++ docs/retype.yml | 37 ++++ docs/widgets/activity.md | 24 +++ docs/widgets/bookmarks.md | 23 +++ docs/widgets/calendar.md | 24 +++ docs/widgets/clock.md | 42 ++++ docs/widgets/custom.md | 32 +++ docs/widgets/docker.md | 34 ++++ docs/widgets/generic.md | 92 +++++++++ docs/widgets/iframe.md | 35 ++++ docs/widgets/index.md | 58 ++++++ docs/widgets/notes.md | 24 +++ docs/widgets/search.md | 27 +++ docs/widgets/system-monitor.md | 56 ++++++ docs/widgets/uptime.md | 48 +++++ docs/widgets/weather.md | 37 ++++ 32 files changed, 2400 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.gitignore create mode 100644 docs/api/index.md create mode 100644 docs/community/contributing.md create mode 100644 docs/community/index.md create mode 100644 docs/community/widgets.md create mode 100644 docs/configuration/appearance.md create mode 100644 docs/configuration/dashboard.md create mode 100644 docs/configuration/index.md create mode 100644 docs/features/docker.md create mode 100644 docs/features/forward-auth.md create mode 100644 docs/features/index.md create mode 100644 docs/features/monitoring.md create mode 100644 docs/features/sso.md create mode 100644 docs/getting-started/index.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/index.md create mode 100644 docs/retype.yml create mode 100644 docs/widgets/activity.md create mode 100644 docs/widgets/bookmarks.md create mode 100644 docs/widgets/calendar.md create mode 100644 docs/widgets/clock.md create mode 100644 docs/widgets/custom.md create mode 100644 docs/widgets/docker.md create mode 100644 docs/widgets/generic.md create mode 100644 docs/widgets/iframe.md create mode 100644 docs/widgets/index.md create mode 100644 docs/widgets/notes.md create mode 100644 docs/widgets/search.md create mode 100644 docs/widgets/system-monitor.md create mode 100644 docs/widgets/uptime.md create mode 100644 docs/widgets/weather.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..991082c --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,45 @@ +name: Build and Deploy Docs + +on: + push: + branches: [docs] + paths: + - 'docs/**' + pull_request: + branches: [docs] + paths: + - 'docs/**' + +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build Retype + uses: retypeapp/action-build@latest + with: + config: docs/retype.yml + + - name: Upload Pages artifact + if: github.ref == 'refs/heads/docs' && github.event_name == 'push' + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.retype + + deploy: + needs: build + if: github.ref == 'refs/heads/docs' && github.event_name == 'push' + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..3fb155b --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +.retype/ diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..71ca27d --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,278 @@ +--- +label: API Reference +icon: code +order: 65 +expanded: false +--- + +# API Reference + +Atom exposes a RESTful API for all operations. All endpoints except onboarding require authentication via session cookie. + +--- + +## Health & System + +### GET /api/health + +Returns the server health status. + +```json +{ + "status": "ok", + "timestamp": "2025-01-01T00:00:00.000Z", + "uptime": 86400 +} +``` + +**Auth required**: No + +--- + +### GET /api/stats + +Returns real-time system statistics. + +```json +{ + "cpuLoad": 23.5, + "memTotal": 16384, + "memUsed": 8192, + "uptime": 86400, + "platform": "linux", + "storage": [ + { "fs": "/dev/sda1", "size": 500000000, "used": 250000000, "mount": "/" } + ] +} +``` + +--- + +## Configuration + +### GET /api/config + +Fetch the current dashboard configuration. + +### POST /api/config + +Save the dashboard configuration. Body must conform to the AppConfig schema. + +**Validation**: Zod schema validated + +--- + +## Status Checking + +### GET /api/status/check + +Check a single service status. + +| Parameter | Type | Description | +|---|---|---| +| `url` | string | Service URL to check | + +```json +{ "up": true, "status": 200, "latency": 145, "method": "fetch" } +``` + +### POST /api/status/batch + +Batch check multiple services (up to 50). + +**Body**: +```json +{ "urls": ["https://example.com", "https://google.com"] } +``` + +**Response**: +```json +{ + "results": { + "https://example.com": { "up": true, "status": 200, "latency": 145 }, + "https://google.com": { "up": true, "status": 301, "latency": 89 } + } +} +``` + +### GET /api/status/ping + +ICMP ping check. + +| Parameter | Type | Description | +|---|---|---| +| `host` | string | Hostname or IP to ping | + +--- + +## Uptime History + +### GET /api/uptime + +| Parameter | Type | Description | +|---|---|---| +| `service_id` | string | Service URL/ID | +| `hours` | number | Time window (1-720, default: 24) | +| `summary` | boolean | Set `true` for all-service summaries | + +```json +{ + "service_id": "https://example.com", + "hours": 24, + "summary": { "uptime_percent": 99.8, "avg_latency": 145, "total_checks": 288 }, + "history": [ + { "timestamp": "...", "status": "up", "latency": 132, "response_code": 200 } + ] +} +``` + +--- + +## Docker + +### GET /api/docker/containers + +List all containers with real-time stats. + +```json +{ + "containers": [ + { + "id": "abc123", + "name": "grafana", + "image": "grafana/grafana:latest", + "state": "running", + "status": "Up 2 hours", + "cpu": "2.5%", + "memory": "128 MB / 512 MB", + "ports": "3000:3000", + "ip": "172.17.0.2" + } + ] +} +``` + +### POST /api/docker/containers/[id]/action + +Perform container actions. + +| Action | Description | +|---|---| +| `start` | Start container | +| `stop` | Stop container | +| `restart` | Restart container | + +--- + +## Users + +### GET /api/users + +List all users (safe fields only — no passwords). + +### POST /api/users + +Create a new user. Body validated with Zod schema. + +### DELETE /api/users + +Delete a user by ID. + +--- + +## Authentication + +### POST /api/auth/login + +Login with username/password. + +### POST /api/auth/logout + +Clear session cookie. + +### POST /api/auth/register + +Register a new user (first user becomes admin). + +### GET /api/auth/session + +Get current session information. + +### GET /api/auth/providers + +List enabled authentication providers (public endpoint for login page). + +--- + +## OAuth2 / OIDC + +### GET /api/oauth/authorize + +OAuth2 authorization endpoint with consent screen. + +### POST /api/oauth/token + +Token endpoint supporting: +- Authorization Code +- Refresh Token +- Client Credentials + +### GET /api/oauth/userinfo + +Returns authenticated user information (OIDC UserInfo). + +### POST /api/oauth/clients + +Manage OAuth2 clients (create/list/update/delete). + +### POST /api/oauth/introspect + +Token introspection (RFC 7662). + +### POST /api/oauth/revoke + +Token revocation (RFC 7009). + +--- + +## SAML + +### GET /api/saml/metadata + +SAML Service Provider metadata XML. + +--- + +## Proxy + +### GET /api/proxy + +CORS proxy for fetching external JSON APIs (used by Generic widgets). + +| Parameter | Type | Description | +|---|---|---| +| `url` | string | External URL to proxy | + +--- + +## Backup + +### GET /api/backup/db + +Download the SQLite database file. + +### POST /api/backup/export + +Export configuration as JSON. + +--- + +## Notes + +### GET /api/notes + +Fetch saved notes. + +### POST /api/notes + +Save notes content. diff --git a/docs/community/contributing.md b/docs/community/contributing.md new file mode 100644 index 0000000..b28e0ae --- /dev/null +++ b/docs/community/contributing.md @@ -0,0 +1,191 @@ +--- +label: Contributing +icon: git-pull-request +order: 80 +--- + +# Contributing to Atom + +Thank you for your interest in contributing to Atom! This guide covers contributing to both the **application code** and the **documentation**. + +--- + +## Documentation Contributions + +The Atom documentation site is built with [Retype](https://retype.com/) and lives in the `docs/` folder of the repository. It's deployed to Cloudflare Pages automatically when changes are merged. + +### Quick Start + +1. **Fork** the repository: [github.com/stackryze/atom-homepage](https://github.com/stackryze/atom-homepage) +2. **Clone** your fork: + ```bash + git clone https://github.com/YOUR-USERNAME/atom-homepage.git + cd atom-homepage + ``` +3. **Create a branch** from `docs`: + ```bash + git checkout docs + git checkout -b docs/your-change-name + ``` +4. **Edit files** in the `docs/` folder +5. **Preview locally** (optional): + ```bash + npx retypeapp start docs/ + ``` +6. **Commit and push**: + ```bash + git add docs/ + git commit -m "docs: your change description" + git push origin docs/your-change-name + ``` +7. **Open a Pull Request** targeting the `docs` branch + +### Documentation Structure + +``` +docs/ +├── retype.yml # Retype project config +├── index.md # Home page +├── getting-started/ # Installation & setup +│ ├── index.md +│ └── installation.md +├── configuration/ # Dashboard & appearance config +│ ├── index.md +│ ├── dashboard.md +│ └── appearance.md +├── features/ # Feature documentation +│ ├── index.md +│ ├── docker.md +│ ├── sso.md +│ ├── monitoring.md +│ └── forward-auth.md +├── widgets/ # Widget documentation +│ ├── index.md +│ ├── system-monitor.md +│ ├── clock.md +│ └── ... (one file per widget) +├── community/ # Community section +│ ├── index.md +│ ├── widgets.md # Community widget presets +│ └── contributing.md # This file +└── api/ # API reference + └── index.md +``` + +### Writing Guidelines + +- Use [Retype Markdown](https://retype.com/guides/markdown/) syntax +- Include frontmatter with `label`, `icon`, and `order` +- Use tabs (`+++ Tab Name`) for multi-option instructions +- Use callouts (`!!!warning`, `!!!info`) for important notes +- Add code blocks with language identifiers +- Link to other docs pages using relative paths (e.g., `/widgets/generic/`) + +--- + +## Community Widget Contributions + +The easiest way to contribute is adding widget presets: + +### Steps + +1. Open `docs/community/widgets.md` +2. Add your widget under the appropriate category heading +3. Include: + - App name and description + - JSON configuration block + - API endpoint and fields table + - Any authentication requirements +4. Submit a PR to the `docs` branch + +### Template + +```markdown +### App Name — Feature Description + +Brief description of what this widget shows. + +\```json +{ + "type": "generic", + "title": "App Name", + "options": { + "url": "https://app.example.com", + "fields": [ + { "label": "Field Name", "path": "json.path" } + ] + } +} +\``` + +| Field | Value | +|---|---| +| Endpoint | `/api/endpoint` | +| Auth | API key via header | +| Displays | Field 1, Field 2 | +``` + +--- + +## Code Contributions + +### Setup + +```bash +git clone https://github.com/stackryze/atom-homepage.git +cd atom-homepage +npm install +npm run dev +``` + +### Development Commands + +| Command | Description | +|---|---| +| `npm run dev` | Start dev server | +| `npm run build` | Production build | +| `npm run lint` | ESLint check (zero warnings) | +| `npm run lint:fix` | Auto-fix lint issues | +| `npm test` | Run Jest tests | +| `npm run test:coverage` | Coverage report | + +### Branch Naming + +| Prefix | Use | +|---|---| +| `feat/` | New features | +| `fix/` | Bug fixes | +| `docs/` | Documentation changes | +| `perf/` | Performance improvements | +| `refactor/` | Code refactoring | + +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +feat: add bookmarks widget +fix: resolve SSO callback URL mismatch +docs: add Pi-hole widget preset +perf: optimize bundle with dynamic imports +``` + +### Pull Request Process + +1. Ensure `npm run lint` passes with zero warnings +2. Ensure `npm run build` succeeds +3. Add tests for new functionality when applicable +4. Update documentation if adding user-facing features +5. Keep PRs focused — one feature/fix per PR + +--- + +## Code of Conduct + +All contributors must follow the [Code of Conduct](https://github.com/stackryze/atom-homepage/blob/main/CODE_OF_CONDUCT.md). Be respectful and constructive in all interactions. + +--- + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/stackryze/atom-homepage/blob/main/LICENSE.md). diff --git a/docs/community/index.md b/docs/community/index.md new file mode 100644 index 0000000..c1ab632 --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,32 @@ +--- +label: Community +icon: people +order: 60 +expanded: true +--- + +# Community + +Atom is an open-source project and we welcome contributions from the community. Whether it's a new widget preset, a bug fix, documentation improvement, or a whole new feature — your contribution matters. + +--- + +## Ways to Contribute + +| Type | Where | Description | +|---|---|---| +| :icon-apps: **Widget Presets** | [Community Widgets](/community/widgets/) | Share widget configurations for popular apps | +| :icon-book: **Documentation** | [Contributing to Docs](/community/contributing/) | Improve or add documentation pages | +| :icon-bug: **Bug Reports** | [GitHub Issues](https://github.com/stackryze/atom-homepage/issues) | Report bugs with reproduction steps | +| :icon-light-bulb: **Feature Requests** | [GitHub Issues](https://github.com/stackryze/atom-homepage/issues) | Suggest new features | +| :icon-code: **Code** | [GitHub PRs](https://github.com/stackryze/atom-homepage/pulls) | Fix bugs or implement features | + +--- + +## Community Links + +- :icon-mark-github: [GitHub Repository](https://github.com/stackryze/atom-homepage) +- :icon-issue-opened: [Issue Tracker](https://github.com/stackryze/atom-homepage/issues) +- :icon-git-pull-request: [Pull Requests](https://github.com/stackryze/atom-homepage/pulls) +- :icon-law: [License (MIT)](https://github.com/stackryze/atom-homepage/blob/main/LICENSE.md) +- :icon-code-of-conduct: [Code of Conduct](https://github.com/stackryze/atom-homepage/blob/main/CODE_OF_CONDUCT.md) diff --git a/docs/community/widgets.md b/docs/community/widgets.md new file mode 100644 index 0000000..2fa70d4 --- /dev/null +++ b/docs/community/widgets.md @@ -0,0 +1,204 @@ +--- +label: Community Widgets +icon: gift +order: 90 +--- + +# Community Widgets + +Community-contributed widget presets and configurations for popular self-hosted applications. These are ready-to-use configurations for the [Generic Widget](/widgets/generic/). + +!!! +**Want to add your own?** See [Contributing to Docs](/community/contributing/) — submit a PR adding your widget preset to this page! +!!! + +--- + +## Media Management + +### Sonarr — Queue Monitor + +Track your Sonarr download queue. + +```json +{ + "type": "generic", + "title": "Sonarr Queue", + "options": { + "preset": "sonarr-queue", + "url": "https://sonarr.example.com", + "apiKey": "your-sonarr-api-key" + } +} +``` + +| Field | Value | +|---|---| +| Endpoint | `/api/v3/queue` | +| Display | Queue count | + +--- + +### Radarr — Queue Monitor + +Track your Radarr movie download queue. + +```json +{ + "type": "generic", + "title": "Radarr Queue", + "options": { + "preset": "radarr-queue", + "url": "https://radarr.example.com", + "apiKey": "your-radarr-api-key" + } +} +``` + +--- + +### Tautulli — Plex Activity + +Monitor active Plex streams and bandwidth. + +```json +{ + "type": "generic", + "title": "Plex Activity", + "options": { + "preset": "tautulli-activity", + "url": "https://tautulli.example.com", + "apiKey": "your-tautulli-api-key" + } +} +``` + +| Field | Value | +|---|---| +| Displays | Stream count, total bandwidth, WAN/LAN bandwidth | + +--- + +## Network & DNS + +### Pi-hole — DNS Summary + +View your Pi-hole ad blocking statistics. + +```json +{ + "type": "generic", + "title": "Pi-hole", + "options": { + "preset": "pihole-summary", + "url": "https://pihole.example.com" + } +} +``` + +| Field | Value | +|---|---| +| Displays | Blocked today, block %, total queries, active clients, domains blocked | + +--- + +### AdGuard Home — Stats + +!!!info Coming Soon +This is a community-requested preset. [Submit a PR](/community/contributing/) to add the AdGuard Home widget configuration! +!!! + +--- + +## System Monitoring + +### Glances — CPU Usage + +Monitor CPU utilization from a Glances instance. + +```json +{ + "type": "generic", + "title": "CPU Usage", + "options": { + "preset": "glances-cpu", + "url": "https://glances.example.com" + } +} +``` + +| Field | Value | +|---|---| +| Displays | Total CPU %, user %, system % | + +--- + +### Glances — Memory Usage + +Monitor memory utilization from a Glances instance. + +```json +{ + "type": "generic", + "title": "Memory", + "options": { + "preset": "glances-mem", + "url": "https://glances.example.com" + } +} +``` + +| Field | Value | +|---|---| +| Displays | Memory used %, free, total | + +--- + +## Container Management + +### Portainer — Stack Count + +View the number of Docker Compose stacks managed by Portainer. + +```json +{ + "type": "generic", + "title": "Portainer Stacks", + "options": { + "preset": "portainer-stacks", + "url": "https://portainer.example.com", + "apiKey": "your-portainer-api-key" + } +} +``` + +--- + +## Submitting a Widget Preset + +Want to share a widget configuration for an app not listed here? We'd love to include it! + +### What to Include + +Your submission should contain: + +1. **App name** and brief description +2. **JSON configuration** — a working widget config +3. **API endpoint** used and what fields are displayed +4. **Authentication notes** — does the API need a key? How to generate one? +5. **Category** — Media, Network, Monitoring, Containers, etc. + +### How to Submit + +1. Fork the [atom-homepage](https://github.com/stackryze/atom-homepage) repository +2. Edit `docs/community/widgets.md` — add your preset following the format above +3. Open a Pull Request targeting the `docs` branch +4. Add the label `community-widget` to your PR + +See the full [Contributing Guide](/community/contributing/) for details. + +--- + +## Request a Widget + +Don't see an app you use? [Open an issue](https://github.com/stackryze/atom-homepage/issues/new?labels=widget-request&title=Widget+Request:+) with the label `widget-request` and the community can help build it! diff --git a/docs/configuration/appearance.md b/docs/configuration/appearance.md new file mode 100644 index 0000000..619cf92 --- /dev/null +++ b/docs/configuration/appearance.md @@ -0,0 +1,84 @@ +--- +label: Appearance +icon: paintbrush +order: 80 +--- + +# Appearance & Themes + +Customize the look and feel of your Atom dashboard. + +--- + +## Theme Mode + +Toggle between **Light** and **Dark** mode using: +- The sun/moon icon in the dashboard header +- The Command Palette (`Ctrl+K` → "Toggle Theme") +- **Settings** → **General** → Theme toggle + +--- + +## Theme Settings + +Access the full theme editor in **Settings** → **Appearance**: + +| Setting | Description | +|---|---| +| Primary Color | Main accent color (default: `#d4a574`) | +| Background Color | Dashboard background color | +| Background Image | Custom background image URL | +| Mode | `light` or `dark` | + +--- + +## Quick Theme Presets + +Atom includes built-in theme presets for quick customization: + +### Dark Mode Presets +- **Warm Amber** — Default warm gold theme +- **Ocean Blue** — Cool blue tones +- **Forest Green** — Natural green palette +- **Rose Pink** — Soft pink accents + +### Light Mode Presets +- **Classic Light** — Clean minimal light theme +- **Warm Sand** — Warm light tones +- **Cool Gray** — Professional gray palette + +--- + +## Custom CSS + +For advanced customization, add custom CSS in **Settings** → **Appearance** → **Custom CSS**: + +```css +/* Example: Custom card border radius */ +.serviceCard { + border-radius: 20px !important; +} + +/* Example: Custom font */ +body { + font-family: 'Inter', sans-serif !important; +} +``` + +--- + +## CSS Variables + +Atom uses CSS custom properties that you can override: + +| Variable | Default (Dark) | Description | +|---|---|---| +| `--bg-primary` | `#0e0e0e` | Main background | +| `--bg-secondary` | `#141210` | Secondary background | +| `--bg-card` | `#1a1a1a` | Card background | +| `--bg-hover` | `#252525` | Hover state background | +| `--text-primary` | `#f0f0f0` | Primary text color | +| `--text-secondary` | `#a1a1aa` | Secondary text color | +| `--accent-color` | `#d4a574` | Accent / brand color | +| `--border-color` | `#222222` | Border color | +| `--radius-md` | `12px` | Default border radius | diff --git a/docs/configuration/dashboard.md b/docs/configuration/dashboard.md new file mode 100644 index 0000000..e066c1e --- /dev/null +++ b/docs/configuration/dashboard.md @@ -0,0 +1,138 @@ +--- +label: Dashboard +icon: table +order: 90 +--- + +# Dashboard Configuration + +The dashboard is the main view of Atom. Configure services, layout, pages, and categories. + +--- + +## Services + +Services are the core of your dashboard. Each service card displays the name, icon, status indicator, and response latency. + +### Adding a Service + +1. Go to **Settings** → **Services** tab +2. Click **Add Service** +3. Fill in the details: + +| Field | Required | Description | +|---|---|---| +| Name | Yes | Display name for the service | +| URL | Yes | Full URL (e.g., `https://grafana.example.com`) | +| Icon | No | Icon from [Simple Icons](https://simpleicons.org/) or [Lucide](https://lucide.dev/) | +| Category | No | Group services (e.g., "Media", "Infrastructure") | +| Description | No | Short description shown on hover | +| Ping Host | No | Custom host/IP for ICMP monitoring instead of HTTP | +| Tags | No | Access control tags (comma-separated) | + +### Bulk Import + +Import multiple services at once via CSV or JSON: + ++++ CSV Format + +```csv +name,url,icon,category +Grafana,https://grafana.example.com,grafana,Monitoring +Portainer,https://portainer.example.com,portainer,Docker +Nextcloud,https://cloud.example.com,nextcloud,Cloud +``` + ++++ JSON Format + +```json +[ + { + "name": "Grafana", + "url": "https://grafana.example.com", + "icon": "grafana", + "category": "Monitoring" + } +] +``` + ++++ + +--- + +## Status Monitoring + +Atom checks service health using multiple methods: + +| Method | When Used | Details | +|---|---|---| +| HTTP HEAD | External URLs | Fast, no body download, follows redirects manually | +| HTTP GET | HEAD returns 405 | Fallback when HEAD is rejected | +| TCP Ping | Internal services | Direct TCP connection check | +| ICMP Ping | Custom ping host | Uses the `ping` field on a service | + +### Status States + +| State | Indicator | Condition | +|---|---|---| +| **Up** | :icon-check-circle: Green | Response received, latency < 500ms | +| **Slow** | :icon-alert: Yellow | Response received, latency ≥ 500ms | +| **Down** | :icon-x-circle: Red | No response or error | +| **Loading** | Pulse animation | Check in progress | + +--- + +## Layout Options + +Configure the dashboard layout in **Settings** → **General**: + +| Option | Values | Description | +|---|---|---| +| Style | `grid`, `list` | Card layout mode | +| Columns | 1–6 | Number of columns in grid mode | +| Gap | 8–32 px | Spacing between cards | +| Container Width | `full`, `centered`, `compact` | Dashboard width | +| Widget Alignment | `left`, `right`, `both` | Widget sidebar position | + +--- + +## Pages + +Organize services into multiple dashboard pages (tabs): + +1. Go to **Settings** → **Pages** +2. Create a new page with a name +3. Assign services to each page +4. Use the tab bar on the dashboard to switch between pages + +--- + +## Categories + +Services can be grouped by category. The dashboard shows a category filter bar when multiple categories exist. + +Set the `category` field on each service. Common examples: +- `Infrastructure` +- `Media` +- `Monitoring` +- `Development` +- `Cloud` + +--- + +## Tag-Based Access Control + +Control which services each user can see using tags: + +1. Assign tags to services (e.g., `admin`, `dev`, `media`) +2. Assign tags to users in **Settings** → **Users** +3. Users only see services matching their tags +4. The special tag `all` grants access to everything +5. Admin users always see all services + +--- + +## Search & Command Palette + +- **Search bar**: Filter services by name or URL in real-time +- **Command Palette** (`Ctrl+K` / `Cmd+K`): Quick navigation to any service, page, or setting diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 0000000..41cb9ff --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,10 @@ +--- +label: Configuration +icon: gear +order: 80 +expanded: true +--- + +# Configuration + +Atom is configured through the web UI. All settings are stored in the SQLite database. diff --git a/docs/features/docker.md b/docs/features/docker.md new file mode 100644 index 0000000..d6dbd12 --- /dev/null +++ b/docs/features/docker.md @@ -0,0 +1,100 @@ +--- +label: Docker Integration +icon: container +order: 90 +--- + +# Docker Integration + +Atom provides a full Docker management interface with real-time container stats. + +--- + +## Setup + +Mount the Docker socket to enable container management: + +```yaml docker-compose.yml +services: + atom: + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro +``` + +| Platform | Socket Path | +|---|---| +| Linux / macOS | `/var/run/docker.sock` | +| Windows | `//./pipe/docker_engine` | + +!!!warning Security Note +Mounting the Docker socket gives Atom full control over your Docker daemon. Use `:ro` (read-only) if you only need monitoring without start/stop/exec capabilities. +!!! + +--- + +## Container Dashboard + +Navigate to the Docker page via the sidebar or Command Palette. The dashboard shows: + +| Column | Description | +|---|---| +| Name | Container name | +| Image | Docker image | +| State | Running, exited, paused, etc. | +| CPU % | Real-time CPU usage | +| Memory | Used / Total (e.g., "128 MB / 512 MB") | +| Ports | Port mappings (host:container) | +| IP | Container private IP | + +--- + +## Container Actions + +| Action | Description | +|---|---| +| :icon-play: **Start** | Start a stopped container | +| :icon-square: **Stop** | Stop a running container | +| :icon-sync: **Restart** | Restart a container | +| :icon-terminal: **Terminal** | Open an interactive shell (exec) | +| :icon-code: **Logs** | View container logs in real-time | + +--- + +## Terminal (Exec) + +The built-in terminal uses [xterm.js](https://xtermjs.org/) to provide a fully interactive shell inside any running container: + +- Full terminal emulation with color support +- Resizable terminal window +- Copy/paste support +- Auto-fit to window size + +--- + +## Docker Widget + +Add a Docker summary widget to your dashboard: + +1. Go to **Settings** → **Widgets** +2. Add a widget with type **Docker** +3. The widget shows total container count and running/stopped status + +--- + +## Performance + +- Container stats are fetched with a **2-second timeout** per container +- Overall list fetch has a **5-second timeout** +- Stats that fail to load gracefully fall back without breaking the UI +- Smart merge prevents UI flickering when stats temporarily fail + +--- + +## Troubleshooting + +| Issue | Solution | +|---|---| +| "Docker not available" | Ensure the Docker socket is mounted in your container | +| No stats showing | Container may be paused or the stats endpoint timed out | +| Permission denied | Check Docker socket permissions (`chmod 666 /var/run/docker.sock` or add user to `docker` group) | +| Windows: socket not found | Use `//./pipe/docker_engine` as the volume mount | diff --git a/docs/features/forward-auth.md b/docs/features/forward-auth.md new file mode 100644 index 0000000..6f88c90 --- /dev/null +++ b/docs/features/forward-auth.md @@ -0,0 +1,127 @@ +--- +label: Forward Auth Proxy +icon: shield +order: 70 +--- + +# Forward Auth Proxy + +Protect external applications using Atom as a forward authentication proxy. + +--- + +## Overview + +Atom can act as an authentication gateway for other services. When a user tries to access a protected application, the reverse proxy checks with Atom whether the user is authenticated. + +--- + +## Setup + +### 1. Add a Protected Application + +Go to **Settings** → **Proxy** and add a new application: + +| Field | Description | +|---|---| +| Name | Application display name | +| Slug | URL path segment (e.g., `grafana` → `/proxy/grafana/*`) | +| Backend URL | Target backend (e.g., `http://grafana:3000`) | +| Require Auth | Enable authentication requirement | +| Allowed Users | Restrict to specific usernames/emails (blank = all users) | +| Inject Headers | Pass auth info as `X-Auth-*` headers to the backend | +| Strip Auth Header | Remove the `Authorization` header before proxying | + +### 2. Configure Your Reverse Proxy + ++++ Traefik + oauth2-proxy + +```yaml +services: + oauth2-proxy: + image: quay.io/oauth2-proxy/oauth2-proxy:latest + environment: + - OAUTH2_PROXY_PROVIDER=oidc + - OAUTH2_PROXY_OIDC_ISSUER_URL=https://atom.example.com + - OAUTH2_PROXY_CLIENT_ID=your-client-id + - OAUTH2_PROXY_CLIENT_SECRET=your-client-secret + - OAUTH2_PROXY_COOKIE_SECRET=generate-a-32-byte-secret + - OAUTH2_PROXY_REDIRECT_URL=https://app.example.com/oauth2/callback + - OAUTH2_PROXY_EMAIL_DOMAINS=* + labels: + - "traefik.http.middlewares.oauth.forwardauth.address=http://oauth2-proxy:4180/oauth2/auth" + - "traefik.http.middlewares.oauth.forwardauth.trustForwardHeader=true" + + grafana: + image: grafana/grafana + labels: + - "traefik.http.routers.grafana.middlewares=oauth@docker" +``` + ++++ Nginx + +```nginx +server { + listen 443 ssl; + server_name app.example.com; + + location /oauth2/ { + proxy_pass http://oauth2-proxy:4180; + } + + location / { + auth_request /oauth2/auth; + auth_request_set $auth_user $upstream_http_x_auth_request_user; + proxy_set_header X-Auth-User $auth_user; + proxy_pass http://backend:8080; + } +} +``` + ++++ Caddy + +``` +app.example.com { + forward_auth oauth2-proxy:4180 { + uri /oauth2/auth + copy_headers X-Auth-Request-User X-Auth-Request-Email + } + reverse_proxy backend:8080 +} +``` + ++++ + +--- + +## Auth Headers + +When **Inject Headers** is enabled, Atom passes the following headers to the backend: + +| Header | Value | +|---|---| +| `X-Auth-User-Id` | Atom user ID | +| `X-Auth-Username` | Username | +| `X-Auth-Email` | User email (if available) | + +--- + +## Generating OAuth Secrets + +```bash +# Generate a cookie secret for oauth2-proxy +openssl rand -hex 16 + +# Or using Python +python3 -c 'import secrets; print(secrets.token_hex(16))' +``` + +--- + +## Production Tips + +1. **Always use HTTPS** in production +2. Set `COOKIE_SECURE=true` behind a TLS-terminating proxy +3. Restrict `email_domains` to your organization +4. Use short session durations for sensitive applications +5. Monitor the Atom audit log for suspicious auth attempts diff --git a/docs/features/index.md b/docs/features/index.md new file mode 100644 index 0000000..d80c014 --- /dev/null +++ b/docs/features/index.md @@ -0,0 +1,10 @@ +--- +label: Features +icon: star +order: 70 +expanded: true +--- + +# Features + +Explore Atom's feature set — from service monitoring to Docker management and SSO. diff --git a/docs/features/monitoring.md b/docs/features/monitoring.md new file mode 100644 index 0000000..0970b0c --- /dev/null +++ b/docs/features/monitoring.md @@ -0,0 +1,89 @@ +--- +label: Status Monitoring +icon: pulse +order: 85 +--- + +# Status Monitoring + +Atom provides real-time uptime monitoring for all your services. + +--- + +## How It Works + +When services are loaded on the dashboard, Atom checks each service's health status using the most appropriate method: + +| Method | When Used | Timeout | +|---|---|---| +| **HTTP HEAD** | External HTTP/HTTPS URLs | 5 seconds | +| **HTTP GET** (fallback) | When HEAD returns 405 | 5 seconds | +| **TCP Ping** | Internal/private network services | 2 seconds | +| **ICMP Ping** | Services with a custom `ping` field | System default | + +### Batch Checking + +Dashboard status checks are batched — up to 50 services checked simultaneously with a concurrency limit of 10 parallel requests to prevent overwhelming your network. + +--- + +## Status Indicators + +| State | Color | Condition | +|---|---|---| +| Up | :icon-check-circle: Green | Response received, latency < 500ms | +| Slow | :icon-alert: Yellow | Response received, latency ≥ 500ms | +| Down | :icon-x-circle: Red | No response, timeout, or error | +| Loading | Pulse animation | Check in progress | + +--- + +## Uptime History + +Atom records every status check in the database. View historical data in the **Uptime Widget** or the **Status Overview** page (`/apps`). + +Data tracked per check: +- Timestamp +- Status (up / slow / down) +- HTTP response code +- Response latency (ms) + +### Status Overview Page + +The `/apps` page shows a summary of all services: +- Total up / slow / down counts +- Average latency per service +- Uptime percentage (24h window) +- Sortable and searchable + +--- + +## Notifications + +The **Notification Center** (bell icon in header) alerts you when: +- A service goes **down** (was previously up) +- A service becomes **slow** (was previously up) +- A service **recovers** (was down, now up) + +--- + +## Private Network Detection + +Atom automatically detects internal services and uses TCP ping instead of HTTP: + +- `localhost`, `127.x.x.x` +- `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x` +- `.local` and `.internal` hostnames +- Hostnames without dots + +--- + +## Custom Ping Host + +For services behind load balancers or reverse proxies, you can set a custom ping host: + +1. Edit the service +2. Set the **Ping** field to a specific IP or hostname +3. Atom uses ICMP ping instead of HTTP for status checks + +This is useful when the HTTP endpoint returns a cached response but you want to check the actual server. diff --git a/docs/features/sso.md b/docs/features/sso.md new file mode 100644 index 0000000..2f1d392 --- /dev/null +++ b/docs/features/sso.md @@ -0,0 +1,155 @@ +--- +label: SSO & Authentication +icon: shield-lock +order: 80 +--- + +# SSO & Authentication + +Atom supports local authentication and external identity providers via OAuth2/OIDC and SAML 2.0. + +--- + +## Local Authentication + +By default, Atom uses local username/password authentication: + +- Passwords are hashed with **bcrypt** (10 salt rounds) +- Sessions use **JWT** tokens stored in HTTP-only cookies +- The first registered user is automatically an **admin** + +--- + +## User Roles + +| Role | Capabilities | +|---|---| +| **Admin** | Full access: manage users, services, settings, OAuth clients, auth providers | +| **Member** | View dashboard, access assigned services (based on tags) | + +--- + +## External Identity Providers + +Atom can authenticate users via any OAuth2/OIDC or SAML 2.0 provider. + +### Supported Provider Presets + +| Provider | Type | Auto-configured | +|---|---|---| +| Google | OIDC | Yes — just add Client ID & Secret | +| GitHub | OAuth2 | Yes | +| Microsoft (Entra ID) | OIDC | Yes | +| GitLab | OIDC | Yes | +| Authentik | OIDC | Yes | +| Keycloak | OIDC | Yes | +| Custom | OIDC / OAuth2 | Manual endpoint configuration | + +### Adding a Provider + +1. Go to **Settings** → **Auth Providers** +2. Click a preset button (e.g., Google) or **Add Custom** +3. Fill in the required fields: + +| Field | Description | +|---|---| +| Name | Display name on the login page | +| Client ID | From your identity provider | +| Client Secret | From your identity provider | +| Issuer | OIDC issuer URL (presets fill this automatically) | +| Scopes | Space-separated (default: `openid profile email`) | + +4. Click **Save** and toggle the provider **Enabled** + +### Provider Settings + +| Setting | Description | +|---|---| +| **User Match Field** | How to match external users to local accounts: `email`, `username`, or `sub` | +| **Auto Register** | Automatically create local accounts for new external users | +| **Auto Launch** | Skip the login page and redirect directly to this provider | + +--- + +## Callback URL + +Each provider needs a callback/redirect URL configured in your identity provider. Atom displays the callback URL on the provider configuration page: + +``` +https://your-atom-url/api/auth/{provider-slug}/callback +``` + +Use the **Copy Callback URL** button in the provider settings. + +--- + +## OIDC Discovery + +If your provider supports OIDC Discovery, Atom can auto-fill endpoints: + +1. Enter the provider's Issuer URL +2. Click **Discover** — Atom fetches the `.well-known/openid-configuration` +3. Authorization, token, userinfo, and JWKS endpoints are filled automatically + +--- + +## SAML 2.0 + +Atom also functions as a SAML Service Provider: + +- **Metadata URL**: `https://your-atom-url/api/saml/metadata` +- Configure your IdP with Atom's metadata +- Set up attribute mapping for email/username + +--- + +## Atom as an Identity Provider + +Atom can also act as an **OAuth2/OIDC provider** for other applications: + +### OIDC Endpoints + +| Endpoint | URL | +|---|---| +| Discovery | `/.well-known/openid-configuration` | +| Authorization | `/api/oauth/authorize` | +| Token | `/api/oauth/token` | +| UserInfo | `/api/oauth/userinfo` | +| Introspect | `/api/oauth/introspect` | +| Revoke | `/api/oauth/revoke` | + +### OAuth2 Grants + +- **Authorization Code** — Standard web app flow with consent screen +- **Refresh Token** — Long-lived sessions +- **Client Credentials** — Machine-to-machine + +### Creating OAuth Clients + +1. Go to **Settings** → **OAuth Clients** +2. Click **Add Client** +3. Configure redirect URIs +4. Use the generated Client ID and Secret in your application + +--- + +## Forward Auth Proxy + +Atom can protect external applications using forward auth: + +1. Go to **Settings** → **Proxy** +2. Add a protected application with its backend URL +3. Configure access control (all users or specific users) +4. Set up your reverse proxy to use Atom's auth endpoint + +See the [Forward Auth Proxy Guide](/features/forward-auth/) for detailed examples. + +--- + +## Environment Variables + +| Variable | Description | +|---|---| +| `COOKIE_SECURE` | Set `true` when behind HTTPS (required for secure cookies) | +| `OAUTH_ISSUER_URL` | Public URL of your Atom instance (required for OIDC/SAML) | +| `OAUTH_TOKEN_EXPIRY` | Token expiration in seconds (default: 3600) | diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..d2282f6 --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,10 @@ +--- +label: Getting Started +icon: rocket +order: 90 +expanded: true +--- + +# Getting Started + +Everything you need to set up and run Atom Dashboard. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..103e0a0 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,205 @@ +--- +label: Installation +icon: download +order: 100 +--- + +# Installation + +Atom can be deployed using Docker (recommended) or run locally for development. + +--- + +## Prerequisites + +| Requirement | Minimum | +|---|---| +| Node.js | 18+ (for local dev) | +| Docker | 20+ (for containerized deployment) | +| RAM | 256 MB minimum, 512 MB recommended | + +--- + +## Docker Compose (Recommended) + +Create a `docker-compose.yml` file: + +```yaml docker-compose.yml +services: + atom: + image: ghcr.io/stackryze/atom-homepage:latest + container_name: atom + ports: + - "3000:3000" + volumes: + - atom_data:/app/data + - /var/run/docker.sock:/var/run/docker.sock:ro + environment: + - NODE_ENV=production + - COOKIE_SECURE=false # Set to true behind HTTPS reverse proxy + deploy: + resources: + limits: + memory: 512M + reservations: + memory: 128M + logging: + driver: json-file + options: + max-size: "10m" + max-file: "3" + restart: unless-stopped + +volumes: + atom_data: +``` + +```bash +docker compose up -d +``` + +!!!warning Docker Socket +Mounting `/var/run/docker.sock` is required for Docker container management. Add `:ro` for read-only access if you don't need exec/start/stop functionality. +!!! + +--- + +## Docker Run + +```bash +docker run -d \ + --name atom \ + -p 3000:3000 \ + -v atom_data:/app/data \ + -v /var/run/docker.sock:/var/run/docker.sock:ro \ + -e NODE_ENV=production \ + --restart unless-stopped \ + ghcr.io/stackryze/atom-homepage:latest +``` + +--- + +## Local Development + +```bash +# Clone the repository +git clone https://github.com/stackryze/atom-homepage.git +cd atom-homepage + +# Install dependencies +npm install + +# Start development server +npm run dev +``` + +The dev server starts at [http://localhost:3000](http://localhost:3000). + +--- + +## Building from Source + +```bash +# Production build +npm run build + +# Start production server +npm start +``` + +Or build your own Docker image: + +```bash +docker build -t atom-homepage . +``` + +--- + +## Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `NODE_ENV` | `development` | Set to `production` for deployments | +| `PORT` | `3000` | Server port | +| `HOSTNAME` | `0.0.0.0` | Bind address (Docker default) | +| `COOKIE_SECURE` | `false` | Set `true` only behind HTTPS reverse proxy | +| `DATA_DIR` | `./data` | Data directory path (Docker: `/app/data`) | +| `OAUTH_ISSUER_URL` | — | Full Atom URL for OIDC/SAML (e.g., `https://atom.example.com`) | +| `OAUTH_TOKEN_EXPIRY` | `3600` | OAuth token expiration in seconds | +| `NEXT_TELEMETRY_DISABLED` | `1` | Disable Next.js telemetry | + +--- + +## Data Persistence + +All data is stored in a SQLite database at `data/atom.db`. The `data/` directory also stores: + +- `keys/` — OIDC signing keys (auto-generated) +- `saml/` — SAML certificates + +!!! +Always mount a persistent volume to `/app/data` in Docker to avoid data loss on container recreation. +!!! + +--- + +## First Run + +1. Open Atom in your browser at `http://localhost:3000` +2. You'll be redirected to the onboarding page +3. Create your admin account (first user is always admin) +4. Start adding services to your dashboard + +--- + +## Reverse Proxy + +When deploying behind a reverse proxy (Nginx, Traefik, Caddy): + +1. Set `COOKIE_SECURE=true` +2. Set `OAUTH_ISSUER_URL` to your public URL +3. Forward the `Host` header +4. Enable WebSocket proxying for terminal features + ++++ Nginx + +```nginx +server { + listen 443 ssl; + server_name atom.example.com; + + location / { + proxy_pass http://localhost:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket support + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +``` + ++++ Traefik + +```yaml +# docker-compose labels +labels: + - "traefik.enable=true" + - "traefik.http.routers.atom.rule=Host(`atom.example.com`)" + - "traefik.http.routers.atom.tls.certresolver=letsencrypt" + - "traefik.http.services.atom.loadbalancer.server.port=3000" +``` + ++++ Caddy + +``` +atom.example.com { + reverse_proxy localhost:3000 +} +``` + ++++ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7b47490 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,128 @@ +--- +label: Home +icon: home +order: 100 +--- + +# Atom Dashboard + +A modern, self-hosted start page and service dashboard with real-time monitoring, Docker integration, SSO authentication, and customizable widgets. + +![Atom Dashboard](https://img.shields.io/badge/Next.js-16-black?logo=next.js) ![React](https://img.shields.io/badge/React-19-blue?logo=react) ![License](https://img.shields.io/badge/License-MIT-green) ![Docker](https://img.shields.io/badge/Docker-Ready-blue?logo=docker) + +--- + +## Features + +:::row::: + +:::column::: +### :icon-server: Service Monitoring +Add your services and monitor their uptime in real-time with HTTP, TCP, and ICMP checks. +::: + +:::column::: +### :icon-container: Docker Integration +View and manage Docker containers with live CPU/memory stats, logs, and terminal access. +::: + +:::column::: +### :icon-shield-lock: SSO & OAuth +Authenticate with Google, GitHub, Microsoft, GitLab, Authentik, Keycloak, or any OIDC/SAML provider. +::: + +:::row-end::: + +:::row::: + +:::column::: +### :icon-paintbrush: Customizable Themes +Light & dark mode, accent colors, background images, and full appearance editor. +::: + +:::column::: +### :icon-apps: Dashboard Widgets +System stats, weather, clock, calendar, bookmarks, notes, Docker summary, and more. +::: + +:::column::: +### :icon-people: Multi-User +Role-based access with admin/member roles, tag-based service visibility, and user management. +::: + +:::row-end::: + +--- + +## Quick Start + ++++ Docker Compose (Recommended) + +```yaml docker-compose.yml +services: + atom: + image: ghcr.io/stackryze/atom-homepage:latest + container_name: atom + ports: + - "3000:3000" + volumes: + - atom_data:/app/data + - /var/run/docker.sock:/var/run/docker.sock:ro + restart: unless-stopped + +volumes: + atom_data: +``` + +```bash +docker compose up -d +``` + ++++ Docker Run + +```bash +docker run -d \ + --name atom \ + -p 3000:3000 \ + -v atom_data:/app/data \ + -v /var/run/docker.sock:/var/run/docker.sock:ro \ + --restart unless-stopped \ + ghcr.io/stackryze/atom-homepage:latest +``` + ++++ Local Development + +```bash +git clone https://github.com/stackryze/atom-homepage.git +cd atom-homepage +npm install +npm run dev +``` + ++++ + +Open [http://localhost:3000](http://localhost:3000) and create your admin account. + +--- + +## Architecture + +| Component | Technology | +|---|---| +| Frontend | Next.js 16, React 19, CSS Modules | +| Backend | Next.js API Routes (Server Components) | +| Database | SQLite via better-sqlite3 | +| Auth | JWT, bcrypt, OIDC, SAML 2.0 | +| Docker | Dockerode API client | +| Icons | Lucide React (800+), Simple Icons (2500+) | + +--- + +## Next Steps + +- [Installation Guide](/getting-started/installation/) — Detailed setup instructions +- [Configuration](/configuration/) — Customize your dashboard +- [Widgets](/widgets/) — Add and configure widgets +- [Docker Integration](/features/docker/) — Container management +- [SSO Setup](/features/sso/) — External authentication +- [Community](/community/) — Contribute widgets and features diff --git a/docs/retype.yml b/docs/retype.yml new file mode 100644 index 0000000..7943bca --- /dev/null +++ b/docs/retype.yml @@ -0,0 +1,37 @@ +input: . +output: .retype + +url: stackryze.github.io/atom-homepage + +branding: + title: Atom + label: Docs + +links: + - text: GitHub + link: https://github.com/stackryze/atom-homepage + icon: mark-github + target: blank + +footer: + copyright: "© Copyright {{ year }}. Atom Dashboard. All rights reserved." + links: + - text: License + link: https://github.com/stackryze/atom-homepage/blob/main/LICENSE.md + - text: Community + link: /community/ + +edit: + repo: https://github.com/stackryze/atom-homepage/edit/ + base: docs + label: Edit this page + +search: + hotkeys: + - "/" + - "k" + +favicon: static/favicon.png + +meta: + title: " | Atom Docs" diff --git a/docs/widgets/activity.md b/docs/widgets/activity.md new file mode 100644 index 0000000..4e7cab1 --- /dev/null +++ b/docs/widgets/activity.md @@ -0,0 +1,24 @@ +--- +label: Activity Log +icon: history +order: 55 +--- + +# Activity Log Widget + +Shows recent service status changes and events. + +--- + +## Features + +- Chronological list of status transitions +- Shows which services went up, down, or became slow +- Timestamped entries +- Auto-updates with dashboard refresh + +--- + +## Configuration + +No additional configuration needed. The widget automatically tracks all status changes across services. diff --git a/docs/widgets/bookmarks.md b/docs/widgets/bookmarks.md new file mode 100644 index 0000000..196aec4 --- /dev/null +++ b/docs/widgets/bookmarks.md @@ -0,0 +1,23 @@ +--- +label: Bookmarks +icon: bookmark +order: 75 +--- + +# Bookmarks Widget + +A quick-access bookmark panel for frequently visited links. + +--- + +## Configuration + +Bookmarks are managed directly within the widget. Add bookmark entries with a name and URL. + +--- + +## Features + +- Add / remove bookmarks +- Click to open in new tab +- Compact display for quick access diff --git a/docs/widgets/calendar.md b/docs/widgets/calendar.md new file mode 100644 index 0000000..ebcb175 --- /dev/null +++ b/docs/widgets/calendar.md @@ -0,0 +1,24 @@ +--- +label: Calendar +icon: calendar +order: 80 +--- + +# Calendar Widget + +An interactive monthly calendar widget. + +--- + +## Features + +- Monthly calendar view +- Today highlighting +- Previous/next month navigation +- "Go to Today" button + +--- + +## Configuration + +No additional configuration needed. The calendar uses the browser's local timezone and date. diff --git a/docs/widgets/clock.md b/docs/widgets/clock.md new file mode 100644 index 0000000..5ca732a --- /dev/null +++ b/docs/widgets/clock.md @@ -0,0 +1,42 @@ +--- +label: Clock +icon: clock +order: 95 +--- + +# Clock Widget + +A digital clock display with optional weather overlay, quick actions, and notification center access. + +--- + +## Features + +- Real-time digital clock (updates every second) +- Weather temperature and conditions (when location is configured) +- Quick action buttons: + - :icon-gear: Settings + - :icon-keyboard: Keyboard shortcuts + - :icon-sync: Refresh dashboard + - :icon-sign-out: Logout +- :icon-bell: Notification center access + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| Weather Location | string | Set in **Settings** → **General** → **Weather Location** | + +The clock widget automatically uses the weather location from your dashboard settings. No per-widget configuration needed. + +--- + +## Weather Data + +Weather data is fetched from the [Open-Meteo API](https://open-meteo.com/) (free, no API key required): + +1. Location name is geocoded to coordinates +2. Current temperature and day/night status is displayed +3. Shows sun :icon-sun: or moon :icon-moon: icon based on time of day diff --git a/docs/widgets/custom.md b/docs/widgets/custom.md new file mode 100644 index 0000000..fc34861 --- /dev/null +++ b/docs/widgets/custom.md @@ -0,0 +1,32 @@ +--- +label: Custom +icon: pencil +order: 40 +--- + +# Custom Widget + +A fully customizable widget for displaying any content. + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| `content` | string | Custom content to display | + +--- + +## Use Cases + +- Static informational text +- Team announcements +- Quick reference information +- Custom HTML content + +--- + +## Notes + +Custom widgets support plain text content. For more advanced use cases, consider the [Iframe Widget](/widgets/iframe/) or [Generic Widget](/widgets/generic/). diff --git a/docs/widgets/docker.md b/docs/widgets/docker.md new file mode 100644 index 0000000..ddcdddb --- /dev/null +++ b/docs/widgets/docker.md @@ -0,0 +1,34 @@ +--- +label: Docker +icon: container +order: 85 +--- + +# Docker Widget + +A compact summary widget showing Docker container counts and status. + +--- + +## Configuration + +| Option | Type | Default | Description | +|---|---|---|---| +| — | — | — | No additional options required | + +Requires the Docker socket to be mounted. See [Docker Integration](/features/docker/). + +--- + +## Data Displayed + +- Total container count +- Running containers +- Stopped containers + +--- + +## Notes + +- This is a **summary widget** — for full container management, use the Docker page (`/docker`) +- Updates on each dashboard refresh diff --git a/docs/widgets/generic.md b/docs/widgets/generic.md new file mode 100644 index 0000000..7b006c6 --- /dev/null +++ b/docs/widgets/generic.md @@ -0,0 +1,92 @@ +--- +label: Generic +icon: code-square +order: 45 +--- + +# Generic Widget + +A flexible widget that consumes any JSON API and displays mapped fields. + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| `url` | string | API endpoint URL | +| `fields` | array | Field mappings (label → JSON path) | +| `method` | string | HTTP method (default: GET) | + +--- + +## Widget Presets + +Atom includes pre-configured presets for popular self-hosted applications: + +### Sonarr Queue +- **Type**: `sonarr-queue` +- **Displays**: Queue count +- **API**: `/api/v3/queue` + +### Radarr Queue +- **Type**: `radarr-queue` +- **Displays**: Queue count +- **API**: `/api/v3/queue` + +### Pi-hole Summary +- **Type**: `pihole-summary` +- **Displays**: Blocked today, block percentage, total queries, active clients, domains blocked +- **API**: `/admin/api.php?summary` + +### Glances CPU +- **Type**: `glances-cpu` +- **Displays**: Total CPU %, user %, system % +- **API**: `/api/3/cpu` + +### Glances Memory +- **Type**: `glances-mem` +- **Displays**: Memory used %, free, total +- **API**: `/api/3/mem` + +### Tautulli Activity +- **Type**: `tautulli-activity` +- **Displays**: Stream count, total bandwidth, WAN/LAN bandwidth +- **API**: `/api/v2?cmd=get_activity` + +### Portainer Stacks +- **Type**: `portainer-stacks` +- **Displays**: Stack count +- **API**: `/api/stacks` + +--- + +## Custom API Widget + +To connect to any JSON API: + +1. Add a **Generic** widget +2. Set the API **URL** +3. Define **fields** mapping — each field maps a display label to a JSON path + +Example for a custom API returning `{ "data": { "users": 42, "active": 38 } }`: + +```json +{ + "url": "https://api.example.com/stats", + "fields": [ + { "label": "Total Users", "path": "data.users" }, + { "label": "Active", "path": "data.active" } + ] +} +``` + +--- + +## Authentication + +If your API requires authentication, the Generic widget uses Atom's built-in CORS proxy (`/api/proxy`) which forwards requests with appropriate headers. + +!!! +Want to share a preset for your favorite app? See [Community Widgets](/community/widgets/) for how to contribute! +!!! diff --git a/docs/widgets/iframe.md b/docs/widgets/iframe.md new file mode 100644 index 0000000..588d202 --- /dev/null +++ b/docs/widgets/iframe.md @@ -0,0 +1,35 @@ +--- +label: Iframe +icon: browser +order: 50 +--- + +# Iframe Widget + +Embed any external webpage directly into your dashboard. + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| `url` | string | URL of the page to embed | +| `height` | number | Widget height in pixels | + +--- + +## Use Cases + +- Embed Grafana dashboards +- Show Uptime Kuma status pages +- Display external monitoring tools +- Embed documentation or wikis + +--- + +## Notes + +!!!warning Same-Origin Policies +Some websites block being embedded in iframes via `X-Frame-Options` or `Content-Security-Policy` headers. If a site doesn't load, it's because the target server blocks iframe embedding. +!!! diff --git a/docs/widgets/index.md b/docs/widgets/index.md new file mode 100644 index 0000000..883ad2a --- /dev/null +++ b/docs/widgets/index.md @@ -0,0 +1,58 @@ +--- +label: Widgets +icon: apps +order: 75 +expanded: true +--- + +# Widgets + +Atom Dashboard supports a variety of built-in widgets to enhance your start page. Widgets can be placed in the left or right sidebar columns and reordered via drag-and-drop. + +Looking for more? Check out [Community Widgets](/community/widgets/) for user-contributed widget ideas and presets. + +--- + +## Managing Widgets + +1. Go to **Settings** → **Widgets** +2. Click **Add Widget** +3. Select a widget type and configure its options +4. Choose the **column** (`left` or `right`) +5. Toggle **enabled/disabled** as needed +6. Drag widgets to reorder them on the dashboard + +--- + +## Built-in Widget Types + +| Type | Description | +|---|---| +| [System Monitor](/widgets/system-monitor/) | Real-time CPU, memory, and storage usage | +| [Clock](/widgets/clock/) | Digital time display with weather overlay | +| [Weather](/widgets/weather/) | Weather conditions for any location | +| [Docker](/widgets/docker/) | Container count summary | +| [Calendar](/widgets/calendar/) | Interactive monthly calendar | +| [Bookmarks](/widgets/bookmarks/) | Quick-access bookmark links | +| [Notes](/widgets/notes/) | Persistent quick notes | +| [Search](/widgets/search/) | Embedded search bar widget | +| [Uptime](/widgets/uptime/) | Uptime history chart for a service | +| [Activity Log](/widgets/activity/) | Recent service status changes | +| [Iframe](/widgets/iframe/) | Embed any external page | +| [Generic](/widgets/generic/) | Flexible JSON API consumer | +| [Custom](/widgets/custom/) | Fully custom HTML/content widget | + +--- + +## Widget Configuration + +All widgets share these common fields: + +| Field | Type | Description | +|---|---|---| +| `id` | string | Auto-generated unique identifier | +| `type` | string | Widget type (see table above) | +| `title` | string | Optional display title | +| `column` | `left` \| `right` | Sidebar placement | +| `enabled` | boolean | Show/hide without deleting | +| `options` | object | Type-specific settings | diff --git a/docs/widgets/notes.md b/docs/widgets/notes.md new file mode 100644 index 0000000..a15acb4 --- /dev/null +++ b/docs/widgets/notes.md @@ -0,0 +1,24 @@ +--- +label: Notes +icon: note +order: 70 +--- + +# Notes Widget + +A persistent quick notes widget for jotting down reminders. + +--- + +## Features + +- Free-text notes area +- Auto-saved to the database +- Persistent across sessions +- Supports plain text + +--- + +## Configuration + +No additional configuration needed. Notes are saved automatically. diff --git a/docs/widgets/search.md b/docs/widgets/search.md new file mode 100644 index 0000000..a4f438f --- /dev/null +++ b/docs/widgets/search.md @@ -0,0 +1,27 @@ +--- +label: Search +icon: search +order: 65 +--- + +# Search Widget + +An embedded search bar widget that searches using your configured search engine. + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| Search Engine | string | Configured in **Settings** → **General** (default: Google) | + +Supported search engines: +- Google +- DuckDuckGo + +--- + +## Usage + +Type a query and press Enter to search using your configured search engine. Opens results in a new tab. diff --git a/docs/widgets/system-monitor.md b/docs/widgets/system-monitor.md new file mode 100644 index 0000000..da70397 --- /dev/null +++ b/docs/widgets/system-monitor.md @@ -0,0 +1,56 @@ +--- +label: System Monitor +icon: cpu +order: 100 +--- + +# System Monitor Widget + +Displays real-time system statistics including CPU usage, memory consumption, and storage information. + +--- + +## Configuration + +| Option | Type | Default | Description | +|---|---|---|---| +| — | — | — | No additional options required | + +--- + +## Data Displayed + +| Metric | Description | +|---|---| +| CPU Load | Current CPU usage percentage | +| Memory Used | Used / Total RAM | +| Storage | Per-disk usage percentage | +| Uptime | System uptime | +| Platform | Operating system name | + +--- + +## API Source + +Data is fetched from the `/api/stats` endpoint which uses the `systeminformation` package: + +```json +{ + "cpuLoad": 23.5, + "memTotal": 16384, + "memUsed": 8192, + "uptime": 86400, + "platform": "linux", + "storage": [ + { "fs": "/dev/sda1", "size": 500000, "used": 250000, "mount": "/" } + ] +} +``` + +--- + +## Notes + +- Updates automatically on each dashboard refresh +- Storage shows all mounted filesystems +- CPU load is a real-time snapshot, not an average diff --git a/docs/widgets/uptime.md b/docs/widgets/uptime.md new file mode 100644 index 0000000..2a2b372 --- /dev/null +++ b/docs/widgets/uptime.md @@ -0,0 +1,48 @@ +--- +label: Uptime +icon: graph +order: 60 +--- + +# Uptime Widget + +Displays uptime history and response time graphs for a specific service. + +--- + +## Configuration + +| Option | Type | Description | +|---|---|---| +| `service_id` | string | The URL/ID of the service to track | +| `hours` | number | Time window (default: 24 hours, max: 720) | + +--- + +## Data Displayed + +- Uptime percentage +- Average latency +- Status history timeline +- Total check count + +--- + +## API Source + +Data is fetched from `/api/uptime?service_id=&hours=`: + +```json +{ + "service_id": "https://example.com", + "hours": 24, + "summary": { + "uptime_percent": 99.8, + "avg_latency": 145, + "total_checks": 288 + }, + "history": [ + { "timestamp": "...", "status": "up", "latency": 132, "response_code": 200 } + ] +} +``` diff --git a/docs/widgets/weather.md b/docs/widgets/weather.md new file mode 100644 index 0000000..6991807 --- /dev/null +++ b/docs/widgets/weather.md @@ -0,0 +1,37 @@ +--- +label: Weather +icon: cloud +order: 90 +--- + +# Weather Widget + +Displays current weather conditions for a configured location. + +--- + +## Configuration + +Set the weather location in **Settings** → **General** → **Weather Location**. + +| Option | Type | Description | +|---|---|---| +| Location | string | City name (e.g., "London", "New York") | + +--- + +## Data Source + +Uses the [Open-Meteo API](https://open-meteo.com/): + +- **Free** — no API key required +- **Geocoding** — city names are automatically converted to coordinates +- **Data**: Temperature, day/night status + +--- + +## Notes + +- Weather data is shared between the Clock and Weather widgets +- Updates on each dashboard load +- No rate limiting concerns with Open-Meteo's free tier From bfb0003d3d2276bef22cadee26098b951603a176 Mon Sep 17 00:00:00 2001 From: VishnuByrraju Date: Tue, 14 Apr 2026 19:39:33 +0530 Subject: [PATCH 2/4] fix: correct Retype action config_path and output dir --- .github/workflows/docs.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 991082c..2341469 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,13 +24,14 @@ jobs: - name: Build Retype uses: retypeapp/action-build@latest with: - config: docs/retype.yml + config_path: docs/retype.yml + output: .retype-output - name: Upload Pages artifact if: github.ref == 'refs/heads/docs' && github.event_name == 'push' uses: actions/upload-pages-artifact@v3 with: - path: docs/.retype + path: .retype-output deploy: needs: build From 96771ca8aa5e3e1713f6bb8bfcf633d35e8744f7 Mon Sep 17 00:00:00 2001 From: VishnuByrraju Date: Tue, 14 Apr 2026 19:42:29 +0530 Subject: [PATCH 3/4] fix: use correct Retype GitHub Pages workflow --- .github/workflows/docs.yml | 38 ++++++++------------------------------ 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2341469..9fc18b6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,46 +1,24 @@ -name: Build and Deploy Docs +name: Deploy Docs on: + workflow_dispatch: push: branches: [docs] - paths: - - 'docs/**' - pull_request: - branches: [docs] - paths: - - 'docs/**' permissions: - contents: read - pages: write - id-token: write + contents: write jobs: - build: + publish: + name: Publish runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Build Retype - uses: retypeapp/action-build@latest + - uses: retypeapp/action-build@latest with: config_path: docs/retype.yml - output: .retype-output - - name: Upload Pages artifact - if: github.ref == 'refs/heads/docs' && github.event_name == 'push' - uses: actions/upload-pages-artifact@v3 + - uses: retypeapp/action-github-pages@latest with: - path: .retype-output - - deploy: - needs: build - if: github.ref == 'refs/heads/docs' && github.event_name == 'push' - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 + update-branch: true From 9e3e70643d7d183860868a90e8bd792c7f607600 Mon Sep 17 00:00:00 2001 From: VishnuByrraju Date: Tue, 14 Apr 2026 20:10:08 +0530 Subject: [PATCH 4/4] fix: workflow runs only from main, protect retype branch --- .github/workflows/docs.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9fc18b6..7c6b28f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,7 +3,9 @@ name: Deploy Docs on: workflow_dispatch: push: - branches: [docs] + branches: [main] + paths: + - 'docs/**' permissions: contents: write