@muhammedaksam/easiarr 0.8.5 → 0.9.1

package/README.md

@@ -118,6 +118,7 @@ bun run start
 ### Infrastructure
 
 - **Traefik** - Reverse proxy and load balancer
+- **Cloudflared** - Cloudflare Tunnel for secure external access
 - **Traefik Certs Dumper** - Extracts certificates from Traefik
 - **CrowdSec** - Intrusion prevention system
 - **Headscale** - Open-source Tailscale control server
@@ -127,6 +128,29 @@ bun run start
 - **PostgreSQL** - Database server
 - **Valkey** - Redis-compatible key-value store
 
+## Cloudflare Tunnel Setup
+
+Expose your services securely without port forwarding using Cloudflare Tunnel.
+
+### Automated Setup (Recommended)
+
+1. Create a Cloudflare API Token at [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens) with:
+   - `Account:Account Settings:Read` (required)
+   - `Account:Cloudflare Tunnel:Edit`
+   - `Zone:DNS:Edit`
+   - `Account:Access: Apps and Policies:Edit` (optional - protects services with email login)
+
+2. Run easiarr → **Main Menu** → **☁️ Cloudflare Tunnel**
+
+3. Paste your API token and follow the wizard
+
+The wizard will automatically:
+
+- Create the tunnel
+- Add DNS records
+- Configure ingress rules
+- Optionally set up email authentication via Cloudflare Access
+
 ## Configuration
 
 easiarr stores its configuration in `~/.easiarr/`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammedaksam/easiarr",
-  "version": "0.8.5",
+  "version": "0.9.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/api/cloudflare-api.ts

@@ -0,0 +1,368 @@
+/**
+ * Cloudflare API client for tunnel and DNS management
+ */
+
+const CLOUDFLARE_API_BASE = "https://api.cloudflare.com/client/v4"
+
+interface CloudflareResponse<T> {
+  success: boolean
+  errors: Array<{ code: number; message: string }>
+  messages: string[]
+  result: T
+}
+
+interface Zone {
+  id: string
+  name: string
+  status: string
+}
+
+interface Tunnel {
+  id: string
+  name: string
+  status: string
+  created_at: string
+  connections: Array<{
+    id: string
+    is_pending_reconnect: boolean
+  }>
+}
+
+interface TunnelCredentials {
+  account_tag: string
+  tunnel_secret: string
+  tunnel_id: string
+  tunnel_name: string
+}
+
+interface DnsRecord {
+  id: string
+  name: string
+  type: string
+  content: string
+  proxied: boolean
+}
+
+export class CloudflareApi {
+  private apiToken: string
+  private accountId: string | null = null
+
+  constructor(apiToken: string) {
+    this.apiToken = apiToken
+  }
+
+  private async request<T>(method: string, endpoint: string, body?: unknown): Promise<CloudflareResponse<T>> {
+    const response = await fetch(`${CLOUDFLARE_API_BASE}${endpoint}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`,
+        "Content-Type": "application/json",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    const data = (await response.json()) as CloudflareResponse<T>
+
+    if (!data.success) {
+      const errors = data.errors.map((e) => e.message).join(", ")
+      throw new Error(`Cloudflare API error: ${errors}`)
+    }
+
+    return data
+  }
+
+  /**
+   * Get account ID from token
+   */
+  async getAccountId(): Promise<string> {
+    if (this.accountId) return this.accountId
+
+    const response = await this.request<{ id: string }[]>("GET", "/accounts")
+    if (response.result.length === 0) {
+      throw new Error(
+        "No Cloudflare accounts found. Your API token is missing the 'Account Settings:Read' permission. " +
+          "Please edit your token in the Cloudflare dashboard and add: Account → Account Settings → Read"
+      )
+    }
+
+    this.accountId = response.result[0].id
+    return this.accountId
+  }
+
+  /**
+   * List all zones (domains) in the account
+   */
+  async listZones(): Promise<Zone[]> {
+    const response = await this.request<Zone[]>("GET", "/zones")
+    return response.result
+  }
+
+  /**
+   * Get zone ID by domain name
+   */
+  async getZoneId(domain: string): Promise<string> {
+    const response = await this.request<Zone[]>("GET", `/zones?name=${encodeURIComponent(domain)}`)
+    if (response.result.length === 0) {
+      throw new Error(`Zone not found for domain: ${domain}`)
+    }
+    return response.result[0].id
+  }
+
+  /**
+   * List all tunnels in the account
+   */
+  async listTunnels(): Promise<Tunnel[]> {
+    const accountId = await this.getAccountId()
+    const response = await this.request<Tunnel[]>("GET", `/accounts/${accountId}/cfd_tunnel`)
+    return response.result
+  }
+
+  /**
+   * Get tunnel by name
+   */
+  async getTunnelByName(name: string): Promise<Tunnel | null> {
+    const tunnels = await this.listTunnels()
+    return tunnels.find((t) => t.name === name) || null
+  }
+
+  /**
+   * Create a new tunnel
+   */
+  async createTunnel(name: string): Promise<{ tunnel: Tunnel; credentials: TunnelCredentials }> {
+    const accountId = await this.getAccountId()
+
+    // Generate a random secret for the tunnel
+    const secret = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("base64")
+
+    const response = await this.request<Tunnel>("POST", `/accounts/${accountId}/cfd_tunnel`, {
+      name,
+      tunnel_secret: secret,
+      config_src: "cloudflare", // Manage config from Cloudflare dashboard/API
+    })
+
+    return {
+      tunnel: response.result,
+      credentials: {
+        account_tag: accountId,
+        tunnel_secret: secret,
+        tunnel_id: response.result.id,
+        tunnel_name: name,
+      },
+    }
+  }
+
+  /**
+   * Get tunnel token (for TUNNEL_TOKEN env var)
+   * The token is base64-encoded JSON containing account_tag, tunnel_id, and tunnel_secret
+   */
+  async getTunnelToken(tunnelId: string): Promise<string> {
+    const accountId = await this.getAccountId()
+    const response = await this.request<string>("GET", `/accounts/${accountId}/cfd_tunnel/${tunnelId}/token`)
+    return response.result
+  }
+
+  /**
+   * Configure tunnel ingress rules
+   */
+  async configureTunnel(
+    tunnelId: string,
+    ingress: Array<{ hostname?: string; service: string; originRequest?: Record<string, unknown> }>
+  ): Promise<void> {
+    const accountId = await this.getAccountId()
+
+    // Ensure there's a catch-all rule at the end
+    const hasChatchAll = ingress.some((r) => !r.hostname)
+    if (!hasChatchAll) {
+      ingress.push({ service: "http_status:404" })
+    }
+
+    await this.request("PUT", `/accounts/${accountId}/cfd_tunnel/${tunnelId}/configurations`, {
+      config: {
+        ingress,
+        "warp-routing": { enabled: false },
+      },
+    })
+  }
+
+  /**
+   * List DNS records for a zone
+   */
+  async listDnsRecords(zoneId: string): Promise<DnsRecord[]> {
+    const response = await this.request<DnsRecord[]>("GET", `/zones/${zoneId}/dns_records`)
+    return response.result
+  }
+
+  /**
+   * Create a CNAME DNS record pointing to the tunnel
+   */
+  async createDnsRecord(zoneId: string, name: string, tunnelId: string, proxied = true): Promise<DnsRecord> {
+    const target = `${tunnelId}.cfargotunnel.com`
+
+    // Check if record already exists
+    const existing = await this.request<DnsRecord[]>(
+      "GET",
+      `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(name)}`
+    )
+
+    if (existing.result.length > 0) {
+      // Update existing record
+      const recordId = existing.result[0].id
+      const response = await this.request<DnsRecord>("PATCH", `/zones/${zoneId}/dns_records/${recordId}`, {
+        type: "CNAME",
+        name,
+        content: target,
+        proxied,
+      })
+      return response.result
+    }
+
+    // Create new record
+    const response = await this.request<DnsRecord>("POST", `/zones/${zoneId}/dns_records`, {
+      type: "CNAME",
+      name,
+      content: target,
+      proxied,
+    })
+
+    return response.result
+  }
+
+  /**
+   * Delete a tunnel
+   */
+  async deleteTunnel(tunnelId: string): Promise<void> {
+    const accountId = await this.getAccountId()
+    await this.request("DELETE", `/accounts/${accountId}/cfd_tunnel/${tunnelId}`)
+  }
+
+  // ==================== Cloudflare Access API ====================
+
+  /**
+   * Create an Access application
+   */
+  async createAccessApplication(
+    domain: string,
+    name = "easiarr",
+    sessionDuration = "24h"
+  ): Promise<{ id: string; name: string }> {
+    const accountId = await this.getAccountId()
+
+    // Check if app already exists
+    const existing = await this.request<Array<{ id: string; name: string; domain: string }>>(
+      "GET",
+      `/accounts/${accountId}/access/apps`
+    )
+
+    const existingApp = existing.result.find((app) => app.name === name || app.domain === `*.${domain}`)
+    if (existingApp) {
+      return { id: existingApp.id, name: existingApp.name }
+    }
+
+    // Create new application
+    const response = await this.request<{ id: string; name: string }>("POST", `/accounts/${accountId}/access/apps`, {
+      name,
+      domain: `*.${domain}`,
+      type: "self_hosted",
+      session_duration: sessionDuration,
+      auto_redirect_to_identity: true,
+    })
+
+    return response.result
+  }
+
+  /**
+   * Create an Access policy for an application
+   */
+  async createAccessPolicy(
+    appId: string,
+    allowedEmails: string[],
+    policyName = "Allow Emails"
+  ): Promise<{ id: string }> {
+    const accountId = await this.getAccountId()
+
+    // Check if policy already exists
+    const existing = await this.request<Array<{ id: string; name: string }>>(
+      "GET",
+      `/accounts/${accountId}/access/apps/${appId}/policies`
+    )
+
+    const existingPolicy = existing.result.find((p) => p.name === policyName)
+    if (existingPolicy) {
+      return { id: existingPolicy.id }
+    }
+
+    // Create email-based allow policy
+    // Each email needs to be a separate include rule
+    // Use next available precedence (existing count + 1)
+    const response = await this.request<{ id: string }>(
+      "POST",
+      `/accounts/${accountId}/access/apps/${appId}/policies`,
+      {
+        name: policyName,
+        decision: "allow",
+        include: allowedEmails.map((email) => ({
+          email: { email },
+        })),
+        precedence: existing.result.length + 1,
+      }
+    )
+
+    return response.result
+  }
+
+  /**
+   * Create Access application with email policy
+   */
+  async setupAccessProtection(
+    domain: string,
+    allowedEmails: string[],
+    appName = "easiarr"
+  ): Promise<{ appId: string; policyId: string }> {
+    const app = await this.createAccessApplication(domain, appName)
+    const policy = await this.createAccessPolicy(app.id, allowedEmails)
+    return { appId: app.id, policyId: policy.id }
+  }
+}
+
+/**
+ * Helper to create a fully configured tunnel with DNS
+ */
+export async function setupCloudflaredTunnel(
+  apiToken: string,
+  domain: string,
+  tunnelName = "easiarr"
+): Promise<{ tunnelToken: string; tunnelId: string }> {
+  const api = new CloudflareApi(apiToken)
+
+  // 1. Check if tunnel already exists
+  let tunnel = await api.getTunnelByName(tunnelName)
+  let tunnelToken: string
+
+  if (tunnel) {
+    // Get existing tunnel token
+    tunnelToken = await api.getTunnelToken(tunnel.id)
+  } else {
+    // 2. Create new tunnel
+    const result = await api.createTunnel(tunnelName)
+    tunnel = result.tunnel
+    tunnelToken = await api.getTunnelToken(tunnel.id)
+  }
+
+  // 3. Configure ingress rules
+  await api.configureTunnel(tunnel.id, [
+    {
+      hostname: `*.${domain}`,
+      service: "http://traefik:80",
+      originRequest: {},
+    },
+  ])
+
+  // 4. Add DNS CNAME record (wildcard)
+  const zoneId = await api.getZoneId(domain)
+  await api.createDnsRecord(zoneId, `*.${domain}`, tunnel.id)
+
+  return {
+    tunnelToken,
+    tunnelId: tunnel.id,
+  }
+}

package/src/apps/registry.ts

@@ -595,7 +595,8 @@ export const APPS: Record<AppId, AppDefinition> = {
     pgid: 0,
     volumes: () => [
       "${HOME}/.easiarr/config.json:/web/config.json:ro",
-      "${HOME}/.easiarr/bookmarks.html:/web/bookmarks.html:ro",
+      "${HOME}/.easiarr/bookmarks-local.html:/web/bookmarks-local.html:ro",
+      "${HOME}/.easiarr/bookmarks-remote.html:/web/bookmarks-remote.html:ro",
     ],
     environment: {
       FOLDER: "/web",
@@ -721,7 +722,8 @@ export const APPS: Record<AppId, AppDefinition> = {
     name: "Traefik",
     description: "Reverse proxy and load balancer",
     category: "infrastructure",
-    defaultPort: 8083,
+    defaultPort: 80,
+    internalPort: 80,
     image: "traefik:latest",
     puid: 0,
     pgid: 0,
@@ -730,20 +732,47 @@ export const APPS: Record<AppId, AppDefinition> = {
       `${root}/config/traefik/letsencrypt:/letsencrypt`,
       "/var/run/docker.sock:/var/run/docker.sock:ro",
     ],
+    // Dashboard exposed on 8083 (internal 8080) for Homepage widget
+    secondaryPorts: ["8083:8080"],
     secrets: [
       {
-        name: "CLOUDFLARE_DNS_API_TOKEN",
-        description: "Cloudflare DNS API Token for Traefik",
+        name: "CLOUDFLARE_DNS_ZONE",
+        description: "Root Domain (e.g. example.com)",
+        required: true,
+      },
+    ],
+    homepage: { icon: "traefik.png", widget: "traefik" },
+  },
+
+  cloudflared: {
+    id: "cloudflared",
+    name: "Cloudflared",
+    description: "Cloudflare Tunnel for secure external access without port forwarding",
+    category: "infrastructure",
+    defaultPort: 0, // No exposed port - tunnel is outbound only
+    image: "cloudflare/cloudflared:latest",
+    puid: 0,
+    pgid: 0,
+    volumes: () => [],
+    environment: {
+      TUNNEL_TOKEN: "${CLOUDFLARE_TUNNEL_TOKEN}",
+    },
+    command: "tunnel run",
+    dependsOn: ["traefik"],
+    secrets: [
+      {
+        name: "CLOUDFLARE_API_TOKEN",
+        description: "Cloudflare API Token (for automated tunnel setup via Menu)",
         required: false,
         mask: true,
       },
       {
-        name: "CLOUDFLARE_DNS_ZONE",
-        description: "Root Domain (e.g. example.com)",
+        name: "CLOUDFLARE_TUNNEL_TOKEN",
+        description: "Cloudflare Tunnel Token (auto-generated or from Zero Trust)",
         required: true,
+        mask: true,
       },
     ],
-    homepage: { icon: "traefik.png", widget: "traefik" },
   },
 
   "traefik-certs-dumper": {

package/src/compose/generator.ts

@@ -9,6 +9,7 @@ import { getComposePath } from "../config/manager"
 import { getApp } from "../apps/registry"
 import { generateServiceYaml } from "./templates"
 import { updateEnv, getLocalIp } from "../utils/env"
+import { saveTraefikConfig } from "./traefik-config"
 
 export interface ComposeService {
   image: string
@@ -22,6 +23,7 @@ export interface ComposeService {
   labels?: string[]
   devices?: string[]
   cap_add?: string[]
+  command?: string
 }
 
 export interface ComposeFile {
@@ -126,12 +128,22 @@ function buildService(appDef: ReturnType<typeof getApp>, appConfig: AppConfig, c
     Object.assign(environment, appConfig.customEnv)
   }
 
+  // Build ports array
+  let ports: string[] = []
+  if (appDef.id !== "plex" && port !== 0 && appDef.defaultPort !== 0) {
+    ports.push(`"${port}:${appDef.internalPort ?? appDef.defaultPort}"`)
+  }
+  // Add secondary ports (e.g., dashboard ports)
+  if (appDef.secondaryPorts) {
+    ports = ports.concat(appDef.secondaryPorts.map((p) => `"${p}"`))
+  }
+
   const service: ComposeService = {
     image: appDef.image,
     container_name: appDef.id,
     environment,
     volumes,
-    ports: appDef.id === "plex" ? [] : [`"${port}:${appDef.internalPort ?? appDef.defaultPort}"`],
+    ports,
     restart: "unless-stopped",
   }
 
@@ -139,6 +151,9 @@ function buildService(appDef: ReturnType<typeof getApp>, appConfig: AppConfig, c
   if (appDef.devices) service.devices = [...appDef.devices]
   if (appDef.cap_add) service.cap_add = [...appDef.cap_add]
 
+  // Add command (e.g., cloudflared)
+  if (appDef.command) service.command = appDef.command
+
   // Plex uses network_mode: host
   if (appDef.id === "plex") {
     service.network_mode = "host"
@@ -152,8 +167,13 @@ function buildService(appDef: ReturnType<typeof getApp>, appConfig: AppConfig, c
     }
   }
 
-  if (config.traefik?.enabled && appDef.id !== "traefik" && appDef.id !== "plex") {
-    service.labels = generateTraefikLabels(appDef.id, appDef.internalPort ?? appDef.defaultPort, config.traefik)
+  if (config.traefik?.enabled && appDef.id !== "plex" && appDef.id !== "cloudflared") {
+    if (appDef.id === "traefik") {
+      // Special labels for Traefik dashboard (accessible via traefik.domain on port 8080)
+      service.labels = generateTraefikLabels("traefik", 8080, config.traefik)
+    } else {
+      service.labels = generateTraefikLabels(appDef.id, appDef.internalPort ?? appDef.defaultPort, config.traefik)
+    }
   }
 
   return service
@@ -200,6 +220,9 @@ export async function saveCompose(config: EasiarrConfig): Promise<string> {
   // Update .env
   await updateEnvFile(config)
 
+  // Generate Traefik config files if Traefik is enabled
+  await saveTraefikConfig(config)
+
   return path
 }
 

package/src/compose/index.ts

@@ -1,2 +1,3 @@
 export * from "./generator"
 export * from "./templates"
+export * from "./traefik-config"

package/src/compose/templates.ts

@@ -10,6 +10,11 @@ export function generateServiceYaml(name: string, service: ComposeService): stri
   yaml += `    image: ${service.image}\n`
   yaml += `    container_name: ${service.container_name}\n`
 
+  // Command (for cloudflared etc.)
+  if (service.command) {
+    yaml += `    command: ${service.command}\n`
+  }
+
   // Network mode (for Plex)
   if (service.network_mode) {
     yaml += `    network_mode: ${service.network_mode}\n`