@muhammedaksam/easiarr 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammedaksam/easiarr",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "TUI tool for generating docker-compose files for the *arr media ecosystem with 41 apps, TRaSH Guides best practices, VPN routing, and Traefik reverse proxy support",
   "module": "src/index.ts",
   "type": "module",

package/src/apps/registry.ts

@@ -29,7 +29,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/movies",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [2000, 2010, 2020, 2030, 2040, 2045, 2050, 2060, 2070, 2080, 2090],
+    prowlarrCategoryIds: [2000], // Movies
+    homepage: { icon: "radarr.png", widget: "radarr" },
   },
 
   sonarr: {
@@ -53,7 +54,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/tv",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [5000, 5010, 5020, 5030, 5040, 5045, 5050, 5060, 5070, 5080, 5090],
+    prowlarrCategoryIds: [5000], // TV
+    homepage: { icon: "sonarr.png", widget: "sonarr" },
   },
 
   lidarr: {
@@ -75,7 +77,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/music",
       apiVersion: "v1",
     },
-    prowlarrCategoryIds: [3000, 3010, 3020, 3030, 3040, 3050, 3060],
+    prowlarrCategoryIds: [3000], // Audio
+    homepage: { icon: "lidarr.png", widget: "lidarr" },
   },
 
   readarr: {
@@ -97,11 +100,12 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/books",
       apiVersion: "v1",
     },
-    prowlarrCategoryIds: [7000, 7010, 7020, 7030, 7040, 7050, 7060],
+    prowlarrCategoryIds: [7000], // Books
     arch: {
       deprecated: ["arm64", "arm32"],
       warning: "Readarr is deprecated - no ARM64 support (project abandoned by upstream)",
     },
+    homepage: { icon: "readarr.png", widget: "readarr" },
   },
 
   bazarr: {
@@ -122,6 +126,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "yaml",
       selector: "auth.apikey",
     },
+    homepage: { icon: "bazarr.png", widget: "bazarr" },
   },
 
   mylar3: {
@@ -166,7 +171,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/adult",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [6000, 6010, 6020, 6030, 6040, 6045, 6050, 6060, 6070, 6080, 6090],
+    prowlarrCategoryIds: [6000], // XXX
+    homepage: { icon: "whisparr.png", widget: "sonarr" }, // Uses sonarr widget type
   },
 
   audiobookshelf: {
@@ -204,6 +210,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "<ApiKey>(.*?)</ApiKey>",
     },
+    homepage: { icon: "prowlarr.png", widget: "prowlarr" },
   },
 
   jackett: {
@@ -268,6 +275,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       },
     ],
     trashGuide: "docs/Downloaders/qBittorrent/",
+    homepage: { icon: "qbittorrent.png", widget: "qbittorrent" },
   },
 
   sabnzbd: {
@@ -288,6 +296,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "api_key\\s*=\\s*(.+)",
     },
+    homepage: { icon: "sabnzbd.png", widget: "sabnzbd" },
   },
 
   // === MEDIA SERVERS ===
@@ -309,6 +318,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: 'PlexOnlineToken="([^"]+)"',
     },
+    homepage: { icon: "plex.png", widget: "plex" },
   },
 
   jellyfin: {
@@ -321,6 +331,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/jellyfin:/config`, `${root}/data/media:/data/media`],
+    homepage: { icon: "jellyfin.png", widget: "jellyfin" },
   },
 
   tautulli: {
@@ -339,6 +350,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "api_key\\s*=\\s*(.+)",
     },
+    homepage: { icon: "tautulli.png", widget: "tautulli" },
   },
 
   tdarr: {
@@ -376,6 +388,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "json",
       selector: "main.apiKey",
     },
+    homepage: { icon: "overseerr.png", widget: "overseerr" },
   },
 
   jellyseerr: {
@@ -436,6 +449,10 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/homepage:/app/config`, "/var/run/docker.sock:/var/run/docker.sock"],
+    environment: {
+      HOMEPAGE_ALLOWED_HOSTS:
+        "homepage,homepage.${CLOUDFLARE_DNS_ZONE},${CLOUDFLARE_DNS_ZONE},localhost,${LOCAL_DOCKER_IP}",
+    },
   },
 
   // === UTILITIES ===
@@ -450,6 +467,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     pgid: 0,
     volumes: (root) => [`${root}/config/portainer:/data`, "/var/run/docker.sock:/var/run/docker.sock"],
     minPasswordLength: 12, // Portainer requires minimum 12 character password
+    homepage: { icon: "portainer.png", widget: "portainer" },
   },
 
   huntarr: {
@@ -562,6 +580,31 @@ export const APPS: Record<AppId, AppDefinition> = {
     volumes: (root) => [`${root}/config/ddns-updater:/data`],
   },
 
+  "easiarr-status": {
+    id: "easiarr-status",
+    name: "Easiarr Status",
+    description: "Exposes Easiarr version for Homepage dashboard",
+    category: "utility",
+    defaultPort: 3009,
+    image: "halverneus/static-file-server:latest",
+    puid: 0,
+    pgid: 0,
+    volumes: (root) => [`${root}/.easiarr:/web:ro`],
+    environment: {
+      FOLDER: "/web",
+      PORT: "3009",
+      CORS: "true",
+    },
+    homepage: {
+      icon: "mdi-docker",
+      widget: "customapi",
+      widgetFields: {
+        url: "http://easiarr-status:3009/config.json",
+        mappings: JSON.stringify([{ field: "version", label: "Installed" }]),
+      },
+    },
+  },
+
   // === VPN ===
   gluetun: {
     id: "gluetun",
@@ -608,6 +651,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "gluetun.png", widget: "gluetun" },
   },
 
   // === MONITORING ===
@@ -621,6 +665,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/grafana:/var/lib/grafana`],
+    homepage: { icon: "grafana.png", widget: "grafana" },
   },
 
   prometheus: {
@@ -633,6 +678,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/prometheus:/prometheus`],
+    homepage: { icon: "prometheus.png" }, // No widget, just icon
   },
 
   dozzle: {
@@ -660,6 +706,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/uptime-kuma:/app/data`, "/var/run/docker.sock:/var/run/docker.sock"],
+    homepage: { icon: "uptime-kuma.png", widget: "uptimekuma" },
   },
 
   // === INFRASTRUCTURE ===
@@ -690,6 +737,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         required: true,
       },
     ],
+    homepage: { icon: "traefik.png", widget: "traefik" },
   },
 
   "traefik-certs-dumper": {
@@ -715,6 +763,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/crowdsec:/etc/crowdsec`, "/var/run/docker.sock:/var/run/docker.sock:ro"],
+    homepage: { icon: "crowdsec.png", widget: "crowdsec" },
   },
 
   headscale: {
@@ -727,6 +776,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/headscale:/etc/headscale`, `${root}/config/headscale/data:/var/lib/headscale`],
+    homepage: { icon: "headscale.png", widget: "headscale" },
   },
 
   headplane: {
@@ -762,6 +812,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "tailscale.png", widget: "tailscale" },
   },
 
   authentik: {
@@ -804,6 +855,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "authentik.png", widget: "authentik" },
   },
 
   "authentik-worker": {

package/src/compose/generator.ts

@@ -8,7 +8,7 @@ import type { EasiarrConfig, AppConfig, TraefikConfig, AppId } from "../config/s
 import { getComposePath } from "../config/manager"
 import { getApp } from "../apps/registry"
 import { generateServiceYaml } from "./templates"
-import { updateEnv } from "../utils/env"
+import { updateEnv, getLocalIp } from "../utils/env"
 
 export interface ComposeService {
   image: string
@@ -212,5 +212,6 @@ async function updateEnvFile(config: EasiarrConfig) {
     PUID: config.uid.toString(),
     PGID: config.gid.toString(),
     UMASK: config.umask,
+    LOCAL_DOCKER_IP: getLocalIp(),
   })
 }

package/src/config/homepage-config.ts

@@ -0,0 +1,247 @@
+/**
+ * Homepage Configuration Generator
+ * Generates services.yaml and other config files for Homepage dashboard
+ */
+
+import { writeFile, mkdir } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { EasiarrConfig, AppCategory } from "./schema"
+import { APP_CATEGORIES } from "./schema"
+import { getApp } from "../apps/registry"
+import { CATEGORY_ORDER } from "../apps/categories"
+import { readEnvSync, getLocalIp } from "../utils/env"
+
+/**
+ * Get the Homepage config directory path
+ */
+export function getHomepageConfigPath(config: EasiarrConfig): string {
+  return join(config.rootDir, "config", "homepage")
+}
+
+/**
+ * Homepage service entry
+ */
+interface HomepageService {
+  href: string
+  icon?: string
+  description?: string
+  ping?: string
+  widget?: {
+    type: string
+    url: string
+    key?: string
+    [key: string]: unknown
+  }
+}
+
+/**
+ * Generate services.yaml content from enabled apps
+ */
+export async function generateServicesYaml(config: EasiarrConfig): Promise<string> {
+  const env = readEnvSync()
+  const localIp = getLocalIp()
+
+  // Group apps by category
+  const categoryGroups = new Map<AppCategory, Array<{ name: string; service: HomepageService }>>()
+
+  for (const appConfig of config.apps) {
+    if (!appConfig.enabled) continue
+
+    const appDef = getApp(appConfig.id)
+    if (!appDef) continue
+
+    // Skip homepage itself
+    if (appDef.id === "homepage") continue
+
+    const port = appConfig.port ?? appDef.defaultPort
+    const baseUrl = `http://${localIp}:${port}`
+
+    const service: HomepageService = {
+      href: baseUrl,
+      description: appDef.description,
+    }
+
+    // Add icon if defined in homepage meta
+    if (appDef.homepage?.icon) {
+      service.icon = appDef.homepage.icon
+    } else {
+      // Default to app ID as icon name
+      service.icon = `${appDef.id}.png`
+    }
+
+    // Add ping for monitoring
+    service.ping = baseUrl
+
+    // Add widget if defined and has API key
+    if (appDef.homepage?.widget) {
+      const apiKey = env[`API_KEY_${appDef.id.toUpperCase()}`]
+
+      service.widget = {
+        type: appDef.homepage.widget,
+        url: baseUrl,
+      }
+
+      if (apiKey) {
+        service.widget.key = apiKey
+      }
+
+      // Add any custom widget fields
+      if (appDef.homepage.widgetFields) {
+        Object.assign(service.widget, appDef.homepage.widgetFields)
+      }
+    }
+
+    // Add to category group
+    const category = appDef.category
+    if (!categoryGroups.has(category)) {
+      categoryGroups.set(category, [])
+    }
+    categoryGroups.get(category)!.push({ name: appDef.name, service })
+  }
+
+  // Build YAML output
+  let yaml = "---\n# Auto-generated by Easiarr\n# https://github.com/muhammedaksam/easiarr\n\n"
+
+  // Add Easiarr info section with two widgets - one for installed, one for latest
+  const localIpForEasiarr = localIp
+  yaml += `Easiarr:\n`
+  // Installed version from local easiarr-status container
+  yaml += `  - Installed:\n`
+  yaml += `      href: https://github.com/muhammedaksam/easiarr\n`
+  yaml += `      icon: mdi-docker\n`
+  yaml += `      description: Your current version\n`
+  yaml += `      widget:\n`
+  yaml += `        type: customapi\n`
+  yaml += `        url: http://${localIpForEasiarr}:3009/config.json\n`
+  yaml += `        refreshInterval: 3600000\n` // 1 hour
+  yaml += `        mappings:\n`
+  yaml += `          - field: version\n`
+  yaml += `            label: Version\n`
+  // Latest version from GitHub API
+  yaml += `  - Latest:\n`
+  yaml += `      href: https://github.com/muhammedaksam/easiarr/releases\n`
+  yaml += `      icon: mdi-github\n`
+  yaml += `      description: Check for updates\n`
+  yaml += `      widget:\n`
+  yaml += `        type: customapi\n`
+  yaml += `        url: https://api.github.com/repos/muhammedaksam/easiarr/releases/latest\n`
+  yaml += `        refreshInterval: 86400000\n` // 24 hours
+  yaml += `        mappings:\n`
+  yaml += `          - field: tag_name\n`
+  yaml += `            label: Version\n`
+  yaml += `          - field: published_at\n`
+  yaml += `            label: Released\n`
+  yaml += `            format: relativeDate\n`
+  yaml += `\n`
+
+  // Use CATEGORY_ORDER for consistent ordering
+  for (const { id: category } of CATEGORY_ORDER) {
+    const services = categoryGroups.get(category)
+    if (!services || services.length === 0) continue
+
+    const categoryName = APP_CATEGORIES[category]
+    yaml += `${categoryName}:\n`
+
+    for (const { name, service } of services) {
+      yaml += `  - ${name}:\n`
+      yaml += `      href: ${service.href}\n`
+
+      if (service.icon) {
+        yaml += `      icon: ${service.icon}\n`
+      }
+
+      if (service.description) {
+        yaml += `      description: ${service.description}\n`
+      }
+
+      if (service.ping) {
+        yaml += `      ping: ${service.ping}\n`
+      }
+
+      if (service.widget) {
+        yaml += `      widget:\n`
+        yaml += `        type: ${service.widget.type}\n`
+        yaml += `        url: ${service.widget.url}\n`
+
+        if (service.widget.key) {
+          yaml += `        key: ${service.widget.key}\n`
+        }
+
+        // Add any other widget fields
+        for (const [key, value] of Object.entries(service.widget)) {
+          if (key !== "type" && key !== "url" && key !== "key") {
+            yaml += `        ${key}: ${value}\n`
+          }
+        }
+      }
+    }
+
+    yaml += "\n"
+  }
+
+  return yaml
+}
+
+/**
+ * Generate settings.yaml with sensible defaults
+ */
+export function generateSettingsYaml(): string {
+  return `---
+# Auto-generated by Easiarr
+# For configuration options: https://gethomepage.dev/configs/settings/
+
+title: Easiarr Dashboard
+
+# Background: "Close-up Photography of Leaves With Droplets"
+# Photo by Sohail Nachiti: https://www.pexels.com/photo/close-up-photography-of-leaves-with-droplets-807598/
+background:
+  image: https://images.pexels.com/photos/807598/pexels-photo-807598.jpeg?cs=srgb&fm=jpg&w=4128&h=3096
+  blur: sm
+  saturate: 50
+  brightness: 50
+  opacity: 50
+
+cardBlur: md
+theme: dark
+color: slate
+
+layout:
+  Media Management:
+    style: row
+    columns: 4
+  Media Servers:
+    style: row
+    columns: 2
+  Download Clients:
+    style: row
+    columns: 2
+`
+}
+
+/**
+ * Save Homepage configuration files
+ */
+export async function saveHomepageConfig(config: EasiarrConfig): Promise<{ services: string; settings: string }> {
+  const configPath = getHomepageConfigPath(config)
+
+  // Ensure directory exists
+  if (!existsSync(configPath)) {
+    await mkdir(configPath, { recursive: true })
+  }
+
+  const servicesPath = join(configPath, "services.yaml")
+  const settingsPath = join(configPath, "settings.yaml")
+
+  // Generate and save services.yaml
+  const servicesYaml = await generateServicesYaml(config)
+  await writeFile(servicesPath, servicesYaml, "utf-8")
+
+  // Generate and save settings.yaml (only if doesn't exist)
+  if (!existsSync(settingsPath)) {
+    const settingsYaml = generateSettingsYaml()
+    await writeFile(settingsPath, settingsYaml, "utf-8")
+  }
+
+  return { services: servicesPath, settings: settingsPath }
+}

package/src/config/manager.ts

@@ -10,6 +10,7 @@ import { join } from "node:path"
 import type { EasiarrConfig } from "./schema"
 import { DEFAULT_CONFIG } from "./schema"
 import { detectTimezone, detectUid, detectGid } from "./defaults"
+import { VersionInfo } from "../VersionInfo"
 
 const CONFIG_DIR_NAME = ".easiarr"
 const CONFIG_FILE_NAME = "config.json"
@@ -48,6 +49,26 @@ export async function configExists(): Promise<boolean> {
   return existsSync(getConfigPath())
 }
 
+/**
+ * Migrate config to current version
+ * Preserves user settings while adding new fields with defaults
+ */
+function migrateConfig(oldConfig: Partial<EasiarrConfig>): EasiarrConfig {
+  return {
+    // Start with defaults for new fields
+    ...DEFAULT_CONFIG,
+    // Preserve all user settings
+    ...oldConfig,
+    // Always update version to current
+    version: VersionInfo.version,
+    // Ensure required fields have values
+    umask: oldConfig.umask ?? "002",
+    apps: oldConfig.apps ?? [],
+    createdAt: oldConfig.createdAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  } as EasiarrConfig
+}
+
 export async function loadConfig(): Promise<EasiarrConfig | null> {
   const configPath = getConfigPath()
 
@@ -57,7 +78,16 @@ export async function loadConfig(): Promise<EasiarrConfig | null> {
 
   try {
     const content = await readFile(configPath, "utf-8")
-    return JSON.parse(content) as EasiarrConfig
+    let config = JSON.parse(content) as EasiarrConfig
+
+    // Auto-migrate if version differs from current package version
+    if (config.version !== VersionInfo.version) {
+      config = migrateConfig(config)
+      // Save migrated config (creates backup first)
+      await saveConfig(config)
+    }
+
+    return config
   } catch (error) {
     console.error("Failed to load config:", error)
     return null

package/src/config/schema.ts

@@ -120,6 +120,7 @@ export type AppId =
   | "guacamole"
   | "guacd"
   | "ddns-updater"
+  | "easiarr-status"
   // VPN
   | "gluetun"
   // Monitoring & Infra
@@ -190,6 +191,18 @@ export interface AppDefinition {
   arch?: ArchCompatibility
   /** Minimum password length requirement for user creation */
   minPasswordLength?: number
+  /** Homepage dashboard configuration */
+  homepage?: HomepageMeta
+}
+
+/** Homepage dashboard widget/service configuration */
+export interface HomepageMeta {
+  /** Icon name from Dashboard Icons (e.g., "radarr.png", "mdi-web") */
+  icon?: string
+  /** Widget type for Homepage (e.g., "radarr", "sonarr", "qbittorrent") */
+  widget?: string
+  /** Custom widget fields if needed */
+  widgetFields?: Record<string, string>
 }
 
 export interface RootFolderMeta {

package/src/ui/App.ts

@@ -12,6 +12,8 @@ import { QuickSetup } from "./screens/QuickSetup"
 import { AppManager } from "./screens/AppManager"
 import { ContainerControl } from "./screens/ContainerControl"
 import { AdvancedSettings } from "./screens/AdvancedSettings"
+import { checkForUpdates } from "../utils/update-checker"
+import { UpdateNotification } from "./components/UpdateNotification"
 
 export type Screen = "main" | "quickSetup" | "appManager" | "containerControl" | "advancedSettings"
 
@@ -40,7 +42,19 @@ export class App {
     if (!this.config) {
       this.navigateTo("quickSetup")
     } else {
-      this.navigateTo("main")
+      // Check for updates before showing main menu
+      const updateInfo = await checkForUpdates()
+
+      if (updateInfo.updateAvailable) {
+        // Show update notification
+        const notification = new UpdateNotification(this.renderer, updateInfo, () => {
+          // After dismissing, show main menu
+          this.navigateTo("main")
+        })
+        this.renderer.root.add(notification)
+      } else {
+        this.navigateTo("main")
+      }
     }
 
     // Handle exit

package/src/ui/components/UpdateNotification.ts

@@ -0,0 +1,101 @@
+/**
+ * Update Notification Component
+ * Popup overlay showing new version available
+ */
+
+import { BoxRenderable, TextRenderable, CliRenderer, KeyEvent } from "@opentui/core"
+import type { UpdateInfo } from "../../utils/update-checker"
+
+export class UpdateNotification extends BoxRenderable {
+  private cliRenderer: CliRenderer
+  private updateInfo: UpdateInfo
+  private onDismiss: () => void
+  private keyHandler: (key: KeyEvent) => void
+
+  constructor(renderer: CliRenderer, updateInfo: UpdateInfo, onDismiss: () => void) {
+    super(renderer, {
+      id: "update-notification",
+      position: "absolute",
+      top: "50%",
+      left: "50%",
+      width: 50,
+      height: 12,
+      marginTop: -6, // Center vertically
+      marginLeft: -25, // Center horizontally
+      flexDirection: "column",
+      borderStyle: "rounded",
+      borderColor: "#50fa7b",
+      padding: 1,
+    })
+
+    this.cliRenderer = renderer
+    this.updateInfo = updateInfo
+    this.onDismiss = onDismiss
+
+    this.buildContent()
+
+    // Key handler
+    this.keyHandler = (key: KeyEvent) => {
+      if (key.name === "return" || key.name === "escape" || key.name === "q") {
+        this.dismiss()
+      }
+    }
+    renderer.keyInput.on("keypress", this.keyHandler)
+  }
+
+  private buildContent(): void {
+    // Header
+    this.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "🎉 Update Available!",
+        fg: "#50fa7b",
+      })
+    )
+
+    // Spacer
+    this.add(new BoxRenderable(this.cliRenderer, { height: 1 }))
+
+    // Version info
+    this.add(
+      new TextRenderable(this.cliRenderer, {
+        content: `Current: v${this.updateInfo.currentVersion}`,
+        fg: "#6272a4",
+      })
+    )
+
+    this.add(
+      new TextRenderable(this.cliRenderer, {
+        content: `Latest:  ${this.updateInfo.latestVersion}`,
+        fg: "#f1fa8c",
+      })
+    )
+
+    // Spacer
+    this.add(new BoxRenderable(this.cliRenderer, { height: 1 }))
+
+    // Update command
+    this.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "Run: bun update -g @muhammedaksam/easiarr",
+        fg: "#8be9fd",
+      })
+    )
+
+    // Spacer
+    this.add(new BoxRenderable(this.cliRenderer, { height: 1 }))
+
+    // Dismiss hint
+    this.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "Press Enter or Esc to continue",
+        fg: "#6272a4",
+      })
+    )
+  }
+
+  private dismiss(): void {
+    this.cliRenderer.keyInput.off("keypress", this.keyHandler)
+    this.destroy()
+    this.onDismiss()
+  }
+}

package/src/ui/screens/HomepageSetup.ts

@@ -0,0 +1,306 @@
+/**
+ * Homepage Setup Screen
+ * Configure Homepage dashboard with enabled apps
+ */
+
+import { BoxRenderable, CliRenderer, TextRenderable, KeyEvent } from "@opentui/core"
+import { createPageLayout } from "../components/PageLayout"
+import { EasiarrConfig } from "../../config/schema"
+import { saveHomepageConfig, generateServicesYaml } from "../../config/homepage-config"
+import { getApp } from "../../apps/registry"
+
+interface SetupResult {
+  name: string
+  status: "pending" | "configuring" | "success" | "error" | "skipped"
+  message?: string
+}
+
+type Step = "menu" | "generating" | "preview" | "done"
+
+export class HomepageSetup extends BoxRenderable {
+  private config: EasiarrConfig
+  private cliRenderer: CliRenderer
+  private onBack: () => void
+  private keyHandler!: (key: KeyEvent) => void
+  private results: SetupResult[] = []
+  private currentStep: Step = "menu"
+  private contentBox!: BoxRenderable
+  private pageContainer!: BoxRenderable
+  private menuIndex = 0
+  private previewContent = ""
+
+  constructor(cliRenderer: CliRenderer, config: EasiarrConfig, onBack: () => void) {
+    const { container: pageContainer, content: contentBox } = createPageLayout(cliRenderer, {
+      title: "Homepage Setup",
+      stepInfo: "Configure Dashboard",
+      footerHint: [
+        { type: "key", key: "↑↓", value: "Navigate" },
+        { type: "key", key: "Enter", value: "Select" },
+        { type: "key", key: "Esc", value: "Back" },
+      ],
+    })
+    super(cliRenderer, { width: "100%", height: "100%" })
+    this.add(pageContainer)
+
+    this.config = config
+    this.cliRenderer = cliRenderer
+    this.onBack = onBack
+    this.contentBox = contentBox
+    this.pageContainer = pageContainer
+
+    this.initKeyHandler()
+    this.refreshContent()
+  }
+
+  private initKeyHandler(): void {
+    this.keyHandler = (key: KeyEvent) => {
+      if (key.name === "escape" || (key.name === "c" && key.ctrl)) {
+        if (this.currentStep === "menu") {
+          this.cleanup()
+        } else {
+          this.currentStep = "menu"
+          this.refreshContent()
+        }
+        return
+      }
+
+      if (this.currentStep === "menu") {
+        this.handleMenuKeys(key)
+      } else if (this.currentStep === "preview" || this.currentStep === "done") {
+        if (key.name === "return" || key.name === "escape") {
+          this.currentStep = "menu"
+          this.refreshContent()
+        }
+      }
+    }
+    this.cliRenderer.keyInput.on("keypress", this.keyHandler)
+  }
+
+  private handleMenuKeys(key: KeyEvent): void {
+    const menuItems = this.getMenuItems()
+
+    if (key.name === "up" && this.menuIndex > 0) {
+      this.menuIndex--
+      this.refreshContent()
+    } else if (key.name === "down" && this.menuIndex < menuItems.length - 1) {
+      this.menuIndex++
+      this.refreshContent()
+    } else if (key.name === "return") {
+      this.executeMenuItem(this.menuIndex)
+    }
+  }
+
+  private getMenuItems(): { name: string; description: string; action: () => void }[] {
+    return [
+      {
+        name: "📊 Generate Services",
+        description: "Create services.yaml with all enabled apps",
+        action: () => this.generateServices(),
+      },
+      {
+        name: "👁️  Preview Config",
+        description: "Preview generated services.yaml",
+        action: () => this.previewServices(),
+      },
+      {
+        name: "📋 Show Enabled Apps",
+        description: "List apps that will be added to Homepage",
+        action: () => this.showEnabledApps(),
+      },
+      {
+        name: "↩️  Back",
+        description: "Return to main menu",
+        action: () => this.cleanup(),
+      },
+    ]
+  }
+
+  private executeMenuItem(index: number): void {
+    const items = this.getMenuItems()
+    if (index >= 0 && index < items.length) {
+      items[index].action()
+    }
+  }
+
+  private async generateServices(): Promise<void> {
+    this.currentStep = "generating"
+    this.results = [{ name: "services.yaml", status: "configuring" }]
+    this.refreshContent()
+
+    try {
+      const paths = await saveHomepageConfig(this.config)
+      this.results[0].status = "success"
+      this.results[0].message = `Saved to ${paths.services}`
+    } catch (error) {
+      this.results[0].status = "error"
+      this.results[0].message = error instanceof Error ? error.message : String(error)
+    }
+
+    this.currentStep = "done"
+    this.refreshContent()
+  }
+
+  private async previewServices(): Promise<void> {
+    this.previewContent = await generateServicesYaml(this.config)
+    this.currentStep = "preview"
+    this.refreshContent()
+  }
+
+  private showEnabledApps(): void {
+    const apps = this.config.apps.filter((a) => a.enabled && a.id !== "homepage")
+
+    this.results = apps.map((app) => {
+      const def = getApp(app.id)
+      const hasWidget = def?.homepage?.widget ? "📊" : "📌"
+      return {
+        name: `${hasWidget} ${def?.name || app.id}`,
+        status: "success" as const,
+        message: def?.description,
+      }
+    })
+
+    if (this.results.length === 0) {
+      this.results = [{ name: "No apps enabled", status: "skipped", message: "Enable apps first" }]
+    }
+
+    this.currentStep = "done"
+    this.refreshContent()
+  }
+
+  private refreshContent(): void {
+    this.contentBox.getChildren().forEach((child) => child.destroy())
+
+    if (this.currentStep === "menu") {
+      this.renderMenu()
+    } else if (this.currentStep === "preview") {
+      this.renderPreview()
+    } else {
+      this.renderResults()
+    }
+  }
+
+  private renderMenu(): void {
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "Configure Homepage dashboard with your enabled apps:\n\n",
+        fg: "#aaaaaa",
+      })
+    )
+
+    this.getMenuItems().forEach((item, idx) => {
+      const pointer = idx === this.menuIndex ? "→ " : "  "
+      const fg = idx === this.menuIndex ? "#50fa7b" : "#8be9fd"
+
+      this.contentBox.add(
+        new TextRenderable(this.cliRenderer, {
+          content: `${pointer}${item.name}\n`,
+          fg,
+        })
+      )
+      this.contentBox.add(
+        new TextRenderable(this.cliRenderer, {
+          content: `    ${item.description}\n\n`,
+          fg: "#6272a4",
+        })
+      )
+    })
+  }
+
+  private renderPreview(): void {
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "Preview: services.yaml\n",
+        fg: "#50fa7b",
+      })
+    )
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "─".repeat(40) + "\n",
+        fg: "#555555",
+      })
+    )
+
+    // Show preview (truncated)
+    const lines = this.previewContent.split("\n").slice(0, 30)
+    for (const line of lines) {
+      this.contentBox.add(
+        new TextRenderable(this.cliRenderer, {
+          content: line + "\n",
+          fg: line.startsWith("#") ? "#6272a4" : line.endsWith(":") ? "#8be9fd" : "#f8f8f2",
+        })
+      )
+    }
+
+    if (this.previewContent.split("\n").length > 30) {
+      this.contentBox.add(
+        new TextRenderable(this.cliRenderer, {
+          content: "\n... (truncated)\n",
+          fg: "#6272a4",
+        })
+      )
+    }
+
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "\nPress Enter or Esc to go back",
+        fg: "#6272a4",
+      })
+    )
+  }
+
+  private renderResults(): void {
+    const headerText = this.currentStep === "done" ? "Results:\n\n" : "Generating...\n\n"
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: headerText,
+        fg: this.currentStep === "done" ? "#50fa7b" : "#f1fa8c",
+      })
+    )
+
+    for (const result of this.results) {
+      let status = ""
+      let fg = "#aaaaaa"
+      switch (result.status) {
+        case "pending":
+          status = "⏳"
+          break
+        case "configuring":
+          status = "🔄"
+          fg = "#f1fa8c"
+          break
+        case "success":
+          status = "✓"
+          fg = "#50fa7b"
+          break
+        case "error":
+          status = "✗"
+          fg = "#ff5555"
+          break
+        case "skipped":
+          status = "⊘"
+          fg = "#6272a4"
+          break
+      }
+
+      let content = `${status} ${result.name}`
+      if (result.message) {
+        content += ` - ${result.message}`
+      }
+
+      this.contentBox.add(new TextRenderable(this.cliRenderer, { content: content + "\n", fg }))
+    }
+
+    this.contentBox.add(
+      new TextRenderable(this.cliRenderer, {
+        content: "\nPress Enter or Esc to continue...",
+        fg: "#6272a4",
+      })
+    )
+  }
+
+  private cleanup(): void {
+    this.cliRenderer.keyInput.off("keypress", this.keyHandler)
+    this.destroy()
+    this.onBack()
+  }
+}

package/src/ui/screens/MainMenu.ts

@@ -16,6 +16,7 @@ import { ProwlarrSetup } from "./ProwlarrSetup"
 import { QBittorrentSetup } from "./QBittorrentSetup"
 import { FullAutoSetup } from "./FullAutoSetup"
 import { MonitorDashboard } from "./MonitorDashboard"
+import { HomepageSetup } from "./HomepageSetup"
 
 export class MainMenu {
   private renderer: RenderContext
@@ -129,6 +130,10 @@ export class MainMenu {
           name: "📊 Monitor Dashboard",
           description: "Configure app health monitoring",
         },
+        {
+          name: "🏠 Homepage Setup",
+          description: "Generate Homepage dashboard config",
+        },
         { name: "❌ Exit", description: "Close easiarr" },
       ],
     })
@@ -227,7 +232,18 @@ export class MainMenu {
           this.container.add(monitor)
           break
         }
-        case 11:
+        case 11: {
+          // Homepage Setup
+          this.menu.blur()
+          this.page.visible = false
+          const homepageSetup = new HomepageSetup(this.renderer as CliRenderer, this.config, () => {
+            this.page.visible = true
+            this.menu.focus()
+          })
+          this.container.add(homepageSetup)
+          break
+        }
+        case 12:
           process.exit(0)
           break
       }

package/src/ui/screens/QuickSetup.ts

@@ -40,6 +40,8 @@ export class QuickSetup {
     "jellyfin",
     "jellyseerr",
     "flaresolverr",
+    "homepage",
+    "easiarr-status",
   ])
 
   private rootDir: string = `${homedir()}/media`

package/src/utils/env.ts

@@ -5,8 +5,31 @@
 
 import { existsSync, readFileSync } from "node:fs"
 import { writeFile, readFile } from "node:fs/promises"
+import { networkInterfaces } from "node:os"
 import { getComposePath } from "../config/manager"
 
+/**
+ * Get the local IP address of the Docker host
+ * Returns the first non-internal IPv4 address found
+ */
+export function getLocalIp(): string {
+  const nets = networkInterfaces()
+
+  for (const name of Object.keys(nets)) {
+    const interfaces = nets[name]
+    if (!interfaces) continue
+
+    for (const net of interfaces) {
+      // Skip internal (loopback) and non-IPv4 addresses
+      if (net.family === "IPv4" && !net.internal) {
+        return net.address
+      }
+    }
+  }
+
+  return "localhost"
+}
+
 /**
  * Get the path to the .env file
  */

package/src/utils/update-checker.ts

@@ -0,0 +1,210 @@
+/**
+ * Update Checker
+ * Check GitHub releases for new easiarr versions
+ */
+
+import { VersionInfo } from "../VersionInfo"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+const GITHUB_REPO = "muhammedaksam/easiarr"
+const CACHE_FILE = join(homedir(), ".easiarr", ".update-cache.json")
+const CACHE_DURATION_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+export interface UpdateInfo {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+  releaseUrl: string
+  releaseNotes?: string
+  publishedAt?: string
+}
+
+interface CachedUpdate {
+  checkedAt: string
+  latestVersion: string
+  releaseUrl: string
+  releaseNotes?: string
+  publishedAt?: string
+}
+
+/**
+ * Get cached update info if still valid
+ */
+function getCachedUpdate(): CachedUpdate | null {
+  if (!existsSync(CACHE_FILE)) return null
+
+  try {
+    const content = readFileSync(CACHE_FILE, "utf-8")
+    const cached = JSON.parse(content) as CachedUpdate
+
+    const checkedAt = new Date(cached.checkedAt).getTime()
+    const now = Date.now()
+
+    // Cache still valid
+    if (now - checkedAt < CACHE_DURATION_MS) {
+      return cached
+    }
+  } catch {
+    // Ignore cache errors
+  }
+
+  return null
+}
+
+/**
+ * Save update info to cache
+ */
+function cacheUpdate(info: Omit<CachedUpdate, "checkedAt">): void {
+  try {
+    const cached: CachedUpdate = {
+      ...info,
+      checkedAt: new Date().toISOString(),
+    }
+    writeFileSync(CACHE_FILE, JSON.stringify(cached, null, 2), "utf-8")
+  } catch {
+    // Ignore cache write errors
+  }
+}
+
+/**
+ * Compare semver versions
+ * Returns true if v2 is newer than v1
+ */
+function isNewerVersion(v1: string, v2: string): boolean {
+  const normalize = (v: string) => v.replace(/^v/, "")
+  const parts1 = normalize(v1).split(".").map(Number)
+  const parts2 = normalize(v2).split(".").map(Number)
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0
+    const p2 = parts2[i] || 0
+    if (p2 > p1) return true
+    if (p2 < p1) return false
+  }
+
+  return false
+}
+
+/**
+ * Fetch latest release from GitHub API
+ */
+async function fetchLatestRelease(): Promise<{
+  version: string
+  url: string
+  notes?: string
+  publishedAt?: string
+} | null> {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${GITHUB_REPO}/releases/latest`, {
+      headers: {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "easiarr-update-checker",
+      },
+    })
+
+    if (!response.ok) {
+      return null
+    }
+
+    const data = (await response.json()) as {
+      tag_name: string
+      html_url: string
+      body?: string
+      published_at?: string
+    }
+
+    return {
+      version: data.tag_name,
+      url: data.html_url,
+      notes: data.body,
+      publishedAt: data.published_at,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Check for updates
+ * Uses cache to avoid repeated API calls
+ */
+export async function checkForUpdates(): Promise<UpdateInfo> {
+  const currentVersion = VersionInfo.version
+
+  // Check cache first
+  const cached = getCachedUpdate()
+  if (cached) {
+    return {
+      currentVersion,
+      latestVersion: cached.latestVersion,
+      updateAvailable: isNewerVersion(currentVersion, cached.latestVersion),
+      releaseUrl: cached.releaseUrl,
+      releaseNotes: cached.releaseNotes,
+      publishedAt: cached.publishedAt,
+    }
+  }
+
+  // Fetch from GitHub
+  const release = await fetchLatestRelease()
+
+  if (!release) {
+    return {
+      currentVersion,
+      latestVersion: currentVersion,
+      updateAvailable: false,
+      releaseUrl: `https://github.com/${GITHUB_REPO}/releases`,
+    }
+  }
+
+  // Cache the result
+  cacheUpdate({
+    latestVersion: release.version,
+    releaseUrl: release.url,
+    releaseNotes: release.notes,
+    publishedAt: release.publishedAt,
+  })
+
+  return {
+    currentVersion,
+    latestVersion: release.version,
+    updateAvailable: isNewerVersion(currentVersion, release.version),
+    releaseUrl: release.url,
+    releaseNotes: release.notes,
+    publishedAt: release.publishedAt,
+  }
+}
+
+/**
+ * Force refresh update check (ignores cache)
+ */
+export async function forceCheckForUpdates(): Promise<UpdateInfo> {
+  const currentVersion = VersionInfo.version
+  const release = await fetchLatestRelease()
+
+  if (!release) {
+    return {
+      currentVersion,
+      latestVersion: currentVersion,
+      updateAvailable: false,
+      releaseUrl: `https://github.com/${GITHUB_REPO}/releases`,
+    }
+  }
+
+  cacheUpdate({
+    latestVersion: release.version,
+    releaseUrl: release.url,
+    releaseNotes: release.notes,
+    publishedAt: release.publishedAt,
+  })
+
+  return {
+    currentVersion,
+    latestVersion: release.version,
+    updateAvailable: isNewerVersion(currentVersion, release.version),
+    releaseUrl: release.url,
+    releaseNotes: release.notes,
+    publishedAt: release.publishedAt,
+  }
+}