diff --git a/Apps/n8n/docker-compose.yml b/Apps/n8n/docker-compose.yml new file mode 100644 index 0000000..e747387 --- /dev/null +++ b/Apps/n8n/docker-compose.yml @@ -0,0 +1,289 @@ +name: n8n + +services: + n8n: + image: n8nio/n8n:2.6.4 + container_name: n8n + restart: unless-stopped + user: "1000:1000" + networks: + - pcs + expose: + - 80 + labels: + - "caddy=n8n-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams 80}}" + volumes: + - /DATA/AppData/$AppID/data/:/home/node/.n8n + environment: + PUID: $PUID + PGID: $PGID + TZ: $TZ + GENERIC_TIMEZONE: $TZ + N8N_PORT: 80 + N8N_PROTOCOL: https + WEBHOOK_URL: https://n8n-${APP_DOMAIN}/ + DB_TYPE: postgresdb + DB_POSTGRESDB_HOST: n8n-postgres + DB_POSTGRESDB_PORT: 5432 + DB_POSTGRESDB_DATABASE: n8n + DB_POSTGRESDB_USER: n8n + DB_POSTGRESDB_PASSWORD: $PCS_DEFAULT_PASSWORD + depends_on: + - postgres + deploy: + resources: + limits: + memory: 1G + cpus: '1.0' + reservations: + memory: 512M + cpu_shares: 70 + + postgres: + image: postgres:16-alpine + container_name: n8n-postgres + restart: unless-stopped + user: "0:0" + networks: + - pcs + volumes: + - /DATA/AppData/$AppID/pgdata/:/var/lib/postgresql/data + environment: + PUID: $PUID + PGID: $PGID + POSTGRES_DB: n8n + POSTGRES_USER: n8n + POSTGRES_PASSWORD: $PCS_DEFAULT_PASSWORD + POSTGRES_INITDB_ARGS: "--encoding=UTF-8" + deploy: + resources: + limits: + memory: 512M + cpus: '0.5' + reservations: + memory: 256M + cpu_shares: 50 + +networks: + pcs: + external: true + +x-casaos: + architectures: + - amd64 + - arm64 + main: n8n + webui_port: 80 + author: Yundera Team + category: Automation + developer: n8n GmbH + store_app_id: n8n + description: + en_us: | + **Powerful workflow automation for technical people - no coding required for most tasks.** + + n8n lets you connect your apps and services together to automate repetitive tasks. Build complex workflows visually with a simple drag-and-drop interface, or write custom code when you need more power. + + **What you can do:** + - **Connect 400+ apps**: Gmail, Slack, Google Sheets, Notion, GitHub, Discord, Telegram, and hundreds more + - **Automate workflows**: Trigger actions based on events, schedules, or webhooks + - **Transform data**: Filter, merge, split, and transform data between services + - **AI workflows**: Build AI-powered automations with OpenAI, Claude, and other AI services + - **Custom code**: Add JavaScript or Python code nodes when you need custom logic + + **Why choose n8n:** + - **Self-hosted**: Your data stays on your server - full privacy and control + - **No vendor lock-in**: Open source with fair-code license + - **Visual editor**: Build workflows with drag-and-drop, no coding needed + - **Powerful**: Handle complex logic with branching, loops, and error handling + - **Community**: Thousands of community-built workflow templates + + Perfect for developers, IT teams, and power users who want to automate their digital workflows without relying on expensive cloud services. + ko_kr: | + **기술 전문가를 위한 강력한 워크플로우 자동화 - 대부분의 작업에 코딩이 필요 없습니다.** + + n8n을 사용하면 앱과 서비스를 연결하여 반복적인 작업을 자동화할 수 있습니다. 간단한 드래그 앤 드롭 인터페이스로 복잡한 워크플로우를 시각적으로 구축하거나, 더 강력한 기능이 필요할 때 커스텀 코드를 작성할 수 있습니다. + + **할 수 있는 일들:** + - **400개 이상의 앱 연결**: Gmail, Slack, Google Sheets, Notion, GitHub, Discord, Telegram 등 + - **워크플로우 자동화**: 이벤트, 스케줄, 웹훅에 따라 동작 트리거 + - **데이터 변환**: 서비스 간 데이터 필터링, 병합, 분할, 변환 + - **AI 워크플로우**: OpenAI, Claude 등 AI 서비스를 활용한 자동화 구축 + - **커스텀 코드**: JavaScript 또는 Python 코드 노드 추가 가능 + + **왜 n8n을 선택해야 할까요:** + - **셀프 호스팅**: 데이터가 서버에 남음 - 완전한 프라이버시와 제어 + - **벤더 종속 없음**: 페어코드 라이선스의 오픈소스 + - **비주얼 에디터**: 드래그 앤 드롭으로 워크플로우 구축, 코딩 불필요 + - **강력함**: 분기, 루프, 에러 처리 등 복잡한 로직 처리 + - **커뮤니티**: 수천 개의 커뮤니티 워크플로우 템플릿 + + 비싼 클라우드 서비스에 의존하지 않고 디지털 워크플로우를 자동화하려는 개발자, IT 팀, 파워 유저에게 완벽합니다. + zh_cn: | + **为技术人员打造的强大工作流自动化工具 - 大多数任务无需编码。** + + n8n 让您将应用和服务连接在一起，自动化重复性任务。通过简单的拖放界面可视化地构建复杂的工作流，或在需要更强大功能时编写自定义代码。 + + **您可以做什么：** + - **连接 400+ 应用**：Gmail、Slack、Google Sheets、Notion、GitHub、Discord、Telegram 等数百种 + - **自动化工作流**：根据事件、计划或 Webhook 触发操作 + - **转换数据**：在服务之间过滤、合并、拆分和转换数据 + - **AI 工作流**：使用 OpenAI、Claude 等 AI 服务构建自动化 + - **自定义代码**：在需要自定义逻辑时添加 JavaScript 或 Python 代码节点 + + **为什么选择 n8n：** + - **自托管**：您的数据留在您的服务器上 - 完全的隐私和控制 + - **无供应商锁定**：公平代码许可的开源项目 + - **可视化编辑器**：通过拖放构建工作流，无需编码 + - **强大**：处理分支、循环和错误处理等复杂逻辑 + - **社区**：数千个社区构建的工作流模板 + + 非常适合想要自动化数字工作流而不依赖昂贵云服务的开发人员、IT 团队和高级用户。 + fr_fr: | + **Automatisation puissante des flux de travail pour les personnes techniques - pas de codage requis pour la plupart des tâches.** + + n8n vous permet de connecter vos applications et services pour automatiser les tâches répétitives. Construisez visuellement des flux de travail complexes avec une interface glisser-déposer simple, ou écrivez du code personnalisé quand vous avez besoin de plus de puissance. + + **Ce que vous pouvez faire :** + - **Connecter 400+ applications** : Gmail, Slack, Google Sheets, Notion, GitHub, Discord, Telegram et des centaines d'autres + - **Automatiser les flux de travail** : Déclencher des actions basées sur des événements, des horaires ou des webhooks + - **Transformer les données** : Filtrer, fusionner, diviser et transformer les données entre les services + - **Flux de travail IA** : Construire des automatisations alimentées par l'IA avec OpenAI, Claude et d'autres services IA + - **Code personnalisé** : Ajouter des nœuds de code JavaScript ou Python quand vous avez besoin de logique personnalisée + + **Pourquoi choisir n8n :** + - **Auto-hébergé** : Vos données restent sur votre serveur - confidentialité et contrôle complets + - **Pas de verrouillage fournisseur** : Open source avec licence fair-code + - **Éditeur visuel** : Construisez des flux de travail par glisser-déposer, sans codage + - **Puissant** : Gérez la logique complexe avec des branches, boucles et gestion d'erreurs + - **Communauté** : Des milliers de modèles de flux de travail créés par la communauté + + Parfait pour les développeurs, les équipes IT et les utilisateurs avancés qui souhaitent automatiser leurs flux de travail numériques sans dépendre de services cloud coûteux. + es_es: | + **Potente automatización de flujos de trabajo para personas técnicas - sin necesidad de codificación para la mayoría de las tareas.** + + n8n te permite conectar tus aplicaciones y servicios para automatizar tareas repetitivas. Construye flujos de trabajo complejos visualmente con una interfaz simple de arrastrar y soltar, o escribe código personalizado cuando necesites más potencia. + + **Lo que puedes hacer:** + - **Conectar 400+ aplicaciones**: Gmail, Slack, Google Sheets, Notion, GitHub, Discord, Telegram y cientos más + - **Automatizar flujos de trabajo**: Disparar acciones basadas en eventos, horarios o webhooks + - **Transformar datos**: Filtrar, fusionar, dividir y transformar datos entre servicios + - **Flujos de trabajo IA**: Construir automatizaciones potenciadas por IA con OpenAI, Claude y otros servicios de IA + - **Código personalizado**: Agregar nodos de código JavaScript o Python cuando necesites lógica personalizada + + **Por qué elegir n8n:** + - **Auto-alojado**: Tus datos permanecen en tu servidor - privacidad y control completos + - **Sin bloqueo de proveedor**: Código abierto con licencia fair-code + - **Editor visual**: Construye flujos de trabajo arrastrando y soltando, sin necesidad de codificar + - **Potente**: Maneja lógica compleja con ramificaciones, bucles y manejo de errores + - **Comunidad**: Miles de plantillas de flujos de trabajo creadas por la comunidad + + Perfecto para desarrolladores, equipos de IT y usuarios avanzados que quieren automatizar sus flujos de trabajo digitales sin depender de costosos servicios en la nube. + icon: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/n8n/icon.png + screenshot_link: + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/n8n/screenshot-1.png + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/n8n/screenshot-2.png + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/n8n/screenshot-3.png + thumbnail: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/n8n/thumbnail.png + tagline: + en_us: Workflow automation for technical people + ko_kr: 기술 전문가를 위한 워크플로우 자동화 + zh_cn: 为技术人员打造的工作流自动化 + fr_fr: Automatisation des flux de travail pour les personnes techniques + es_es: Automatización de flujos de trabajo para personas técnicas + title: + en_us: n8n + tips: + before_install: + en_us: | + **🔒 Account Setup:** + On first launch, you'll be asked to create an owner account. + Choose your email and password to get started. + + **✨ Features Available:** + • Connect 400+ apps and services + • Visual drag-and-drop workflow editor + • AI-powered automations (OpenAI, Claude, etc.) + • Webhook support for external triggers + • JavaScript and Python custom code nodes + • Scheduled workflow execution + + **🌐 Access:** + Once ready, your app will be available at `https://n8n-[username].nsl.sh` + + **How to use:** + Create your first workflow by clicking the "+" button and connecting nodes together! + ko_kr: | + **🔒 계정 설정:** + 첫 실행 시 소유자 계정을 생성하라는 안내가 표시됩니다. + 이메일과 비밀번호를 선택하여 시작하세요. + + **✨ 사용 가능한 기능:** + • 400개 이상의 앱과 서비스 연결 + • 비주얼 드래그 앤 드롭 워크플로우 에디터 + • AI 기반 자동화 (OpenAI, Claude 등) + • 외부 트리거를 위한 웹훅 지원 + • JavaScript 및 Python 커스텀 코드 노드 + • 예약된 워크플로우 실행 + + **🌐 접근:** + 준비가 되면 `https://n8n-[username].nsl.sh`로 앱에 접근할 수 있습니다! + + **사용 방법:** + "+" 버튼을 클릭하고 노드를 연결하여 첫 번째 워크플로우를 만들어 보세요! + zh_cn: | + **🔒 账户设置:** + 首次启动时，系统会要求您创建所有者账户。 + 选择您的电子邮件和密码即可开始使用。 + + **✨ 可用功能:** + • 连接 400+ 应用和服务 + • 可视化拖放工作流编辑器 + • AI 驱动的自动化（OpenAI、Claude 等） + • 用于外部触发器的 Webhook 支持 + • JavaScript 和 Python 自定义代码节点 + • 定时工作流执行 + + **🌐 访问:** + 准备就绪后，您的应用将通过 `https://n8n-[username].nsl.sh` 可用！ + + **如何使用:** + 点击 "+" 按钮并连接节点来创建您的第一个工作流！ + fr_fr: | + **🔒 Configuration du compte :** + Au premier lancement, vous serez invité à créer un compte propriétaire. + Choisissez votre e-mail et votre mot de passe pour commencer. + + **✨ Fonctionnalités disponibles :** + • Connecter 400+ applications et services + • Éditeur visuel de flux de travail par glisser-déposer + • Automatisations alimentées par l'IA (OpenAI, Claude, etc.) + • Support webhook pour les déclencheurs externes + • Nœuds de code personnalisé JavaScript et Python + • Exécution planifiée des flux de travail + + **🌐 Accès :** + Une fois prêt, votre application sera disponible à `https://n8n-[username].nsl.sh` ! + + **Comment utiliser :** + Créez votre premier flux de travail en cliquant sur le bouton "+" et en connectant les nœuds ensemble ! + es_es: | + **🔒 Configuración de cuenta:** + En el primer inicio, se te pedirá crear una cuenta de propietario. + Elige tu correo electrónico y contraseña para comenzar. + + **✨ Características disponibles:** + • Conectar 400+ aplicaciones y servicios + • Editor visual de flujos de trabajo con arrastrar y soltar + • Automatizaciones potenciadas por IA (OpenAI, Claude, etc.) + • Soporte de webhooks para disparadores externos + • Nodos de código personalizado JavaScript y Python + • Ejecución programada de flujos de trabajo + + **🌐 Acceso:** + Una vez listo, tu aplicación estará disponible en `https://n8n-[username].nsl.sh`! + + **Cómo usar:** + ¡Crea tu primer flujo de trabajo haciendo clic en el botón "+" y conectando los nodos! + index: / diff --git a/Apps/n8n/icon.png b/Apps/n8n/icon.png new file mode 100644 index 0000000..e91bc26 Binary files /dev/null and b/Apps/n8n/icon.png differ diff --git a/Apps/n8n/screenshot-1.png b/Apps/n8n/screenshot-1.png new file mode 100644 index 0000000..ba1b921 Binary files /dev/null and b/Apps/n8n/screenshot-1.png differ diff --git a/Apps/n8n/screenshot-2.png b/Apps/n8n/screenshot-2.png new file mode 100644 index 0000000..90f2cb8 Binary files /dev/null and b/Apps/n8n/screenshot-2.png differ diff --git a/Apps/n8n/screenshot-3.png b/Apps/n8n/screenshot-3.png new file mode 100644 index 0000000..6733acf Binary files /dev/null and b/Apps/n8n/screenshot-3.png differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2bc9f0..9bc346e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,21 +8,28 @@ This document describes how to contribute an app to the Yundera Compose AppStore Before submitting your PR, ensure your app meets these requirements: +### Tech Checklist +- [ ] Proper file permissions based on volume usage. See [Permission Strategy](#permission-strategy) for details +- [ ] Migration path from previous versions is tested - only incremental migration is supported (if a user wants to go from v1.1 to v1.4, they must execute v1.2 and v1.3 first) +- [ ] **Pre-install and Post-install commands security**: If using `pre-install-cmd` or `post-install-cmd`, ensure specific version tags (no `:latest`) and proper user permissions (`--user $PUID:$PGID` when writing to user directories) + ### Security Checklist - [ ] Default authentication (Basic Auth, OAuth, etc.) is enabled and documented - exceptions must be explained in rationale.md (e.g., public websites) - Example of valid exception: - A public website that does not require authentication - The app handle authentication configuration on first launch via an onboarding process (eg Jellyfin, Immich, etc.) - [ ] No hardcoded credentials in the compose file - use environment variables or secrets -- [ ] Proper file permissions based on volume usage. See [Permission Strategy](#permission-strategy) for details - [ ] Specific version tag (no `:latest`) -- [ ] Resource limits are mandatory and set appropriately (on all services in case of multiple services) - exceptions must be explained in rationale.md -- [ ] Migration path from previous versions is tested - only incremental migration is supported (if a user wants to go from v1.1 to v1.4, they must execute v1.2 and v1.3 first) ### Functionality Checklist - [ ] Works immediately after installation - no need to check logs or run commands - pre-install scripts create sensible defaults - [ ] Data is mapped to appropriate `/DATA` subdirectories - if things are mapped outside of /DATA, this should be explained in rationale.md - [ ] No manual configuration required for basic functionality - should work out of the box +- [ ] Data persistence requirements are met - see [Data Persistence](#data-persistence) section for details +- [ ] CPU field cpu_shares is set appropriately (on all services) +- [ ] fresh installation tested +- [ ] uninstall/reinstall tested - An application should be able to be uninstalled and reinstalled without losing user data or configuration (See the keep user data option when uninstalling) + ### Documentation Checklist - [ ] Clear description of the application @@ -56,6 +63,32 @@ To ensure easy testing, please follow these steps: ## Guidelines +### Data Persistence + +Applications must be designed to preserve user data across uninstallation and reinstallation cycles. This ensures users never lose their personal data when updating or reinstalling applications. + +**Requirements:** +- **Persistent Volume Mapping**: All user data, configurations, and databases must be stored in volumes mapped to `/DATA/AppData/[AppName]/` +- **Graceful Data Reuse**: Applications must detect and reuse existing data when reinstalled +- **No Data Erasure**: Container startup processes must never erase or overwrite existing user data +- **Configuration Preservation**: Settings, user accounts, and preferences should persist across container lifecycle + +**Implementation Guidelines:** +- Map all persistent data to `/DATA/AppData/[AppName]/` subdirectories +- Use initialization scripts that check for existing data before creating defaults +- Ensure database migrations are handled gracefully on version updates +- Test uninstall/reinstall scenarios to verify data persistence + +**Example Volume Mapping:** +```yaml +volumes: + - /DATA/AppData/myapp/config:/app/config + - /DATA/AppData/myapp/database:/var/lib/database + - /DATA/AppData/myapp/uploads:/app/uploads +``` + +This approach ensures that when users uninstall and reinstall applications, they can continue from where they left off without losing any personal data or configurations. + ### File Structure Understanding the directory structure is essential for proper app development and data management. All user data and application configurations are stored under `/DATA`: @@ -70,8 +103,8 @@ and Yundera uses a dual permission model to balance security and usability: Files owned by `PUID:PGID` (usually `1000:1000` for the 'pcs:pcs' user) -if no "user" field is specified in the compose file, the container will run as PUID:PGID (different behavior than the docker default so be carful) -if you need to run as root, you must specify `user: 0:0` in the compose file and set the `PUID` and `PGID` to `0:0` in the environment variables. +**if no "user" field is specified in the compose file, the container will run as PUID:PGID (different behavior than the docker default so be carful)** +if you need to run as root, you must specify `user: 0:0` in the compose file. **User-Friendly Directories** @@ -82,13 +115,27 @@ if you need to run as root, you must specify `user: 0:0` in the compose file and - Applications accessing these directories **must** use `user: $PUID:$PGID` **AppData Directories** -- Root ownership acceptable but preferably `PUID:PGID` to allow user to change configurations easily -- `/DATA/AppData/[AppName]/` - Application-specific data and configurations +Contains the App folder : `/DATA/AppData/[AppName]/` - Application-specific data and configurations + +- Root ownership withing the App folder is acceptable but preferably `PUID:PGID` to allow user to change configurations easily - Contains databases, config files, cache, logs, and internal app data -- Users should **not** directly modify these files (system-managed) - Root containers are acceptable when volumes map exclusively to AppData - Examples: `/DATA/AppData/immich/pgdata`, `/DATA/AppData/immich/model-cache` +The App folder should always be owned by `PUID:PGID` to allow the user to romove the folder if needed. +inside this folder the permission may vary depending on usage. + +example`: +``` +root@yundera:/DATA/AppData# ls -al +drwxr-xr-x 13 pcs pcs 4096 Sep 3 14:17 . +drwxrwxrwx 8 pcs pcs 4096 Sep 3 14:17 .. +drwxr-xr-x 5 pcs pcs 4096 Sep 4 12:12 casaos +drwxr-xr-x 3 pcs pcs 4096 Jun 25 10:30 duplicati +drwxr-xr-x 3 pcs pcs 4096 Aug 3 19:35 filebrowser +drwxr-xr-x 4 pcs pcs 4096 Jun 25 10:30 jellyfin +``` + **Mixed Usage Applications:** - If an app needs both AppData and user directory access, use `user: $PUID:$PGID` - Alternative: Use separate containers (one for system tasks, one for user file access) @@ -175,6 +222,61 @@ This structure ensures: - Easy backup and migration - Consistent file permissions with PUID/PGID +### CPU Share Guidelines + +It is mandatory to set CPU shares for all services in your compose file. This helps ensure fair resource allocation and prevents any single container from monopolizing CPU resources. + +CPU shares determine relative CPU priority between containers. Higher values get more CPU time when the system is under load. + +**Formula:** `cpu_shares: [value]` (relative weight, not percentage) + +#### CPU Share Allocation: +``` +**100 - System Critical** (Reserved) +- System services that must never be starved + +**90 - Administrative Critical** +- Applications that must always be responsive with no heavy background processes +- Examples: CasaOS, Portainer, admin dashboards, monitoring tools + +**80 - User-Facing Interactive** +- Real-time applications requiring immediate user responsiveness +- Examples: Web servers, frontend applications, API backends, reverse proxies + +**70 - Interactive with Heavy Tasks** +- Real-time applications that may have intensive background processes +- Examples: Nextcloud (web + background jobs), WebRTC servers, databases serving interactive apps + +**50 - Standard Applications** (Default) +- Regular applications without special performance requirements +- Examples: Most containerized applications, file servers, basic services + +**30 - Background Services** +- Non-interactive services that don't require immediate responsiveness +- Examples: Backup services (Duplicati), log aggregation, scheduled tasks + +**20 - Heavy Background Processing** +- Resource-intensive background tasks with no real-time requirements +- Examples: Machine learning services (Immich ML), video transcoding, batch processing + +**10 - System Background** (Reserved) +- Reserved for system maintenance tasks +``` + +#### Resource limits + +Optional +Only add if necessary to prevent resource exhaustion but most application don't need it. + +```yaml + deploy: + resources: + limits: + memory: 512M +``` + +3. **Testing**: Consider your server's typical load when choosing values + ### Project Structure ```shell @@ -237,18 +339,25 @@ Each directory under [Apps](Apps) corresponds to a Compose App. The directory sh source: /DATA/AppData/$AppID/config # $AppID = app name, e.g. syncthing ``` -- **System Variables**: CasaOS now provides additional system-wide variables for enhanced functionality: +- **System Variables**: CasaOS provides additional system-wide variables for enhanced functionality. These environment variables are automatically injected by CasaOS at container creation: ```yaml environment: - PGID: $PGID # Preset Group ID - PUID: $PUID # Preset User ID - TZ: $TZ # Current system timezone - PASSWORD: $default_pwd # Secure default password generated by CasaOS - DOMAIN: $domain # Domain (or subdomain) mapped to this container - PUBLIC_IP: $public_ip # Public IP used for port binding and announcements + # Standard system variables + PGID: $PGID # Preset Group ID + PUID: $PUID # Preset User ID + TZ: $TZ # Current system timezone + + # V2 system variables (recommended) + PCS_DEFAULT_PASSWORD: $PCS_DEFAULT_PASSWORD # Secure default password generated by CasaOS + PCS_DOMAIN: $PCS_DOMAIN # Domain without https:// (e.g., example.com) + PCS_DATA_ROOT: $PCS_DATA_ROOT # Data root directory (/DATA) + PCS_PUBLIC_IP: $PCS_PUBLIC_IP # Public IP for port binding and announcements + PCS_EMAIL: $PCS_EMAIL # Admin email (admin@DOMAIN) ``` + **Note:** The V2 variable names (prefixed with `PCS_`) are the current standard. Use these in new applications for consistency across the CasaOS ecosystem. + - CasaOS specific metadata, also called *store info*, are stored under the [extension](https://docs.docker.com/compose/compose-file/#extension) property `x-casaos`. #### Compose App Level Configuration @@ -288,9 +397,9 @@ x-casaos: before_install: en_us: | Default Account - | Username | Password | - | -------- | ------------ | - | `admin` | `$default_pwd` | + | Username | Password | + | -------- | ----------------------- | + | `admin` | `$PCS_DEFAULT_PASSWORD` | ``` ### Features @@ -309,13 +418,19 @@ x-casaos: When using `pre-install-cmd`, ensure the command is idempotent and does not require user interaction. Also ensure that versions are specified for any images used in the command to avoid unexpected changes. +**SECURITY REQUIREMENTS for pre-install-cmd:** +- [ ] **Specific version tags**: Never use `:latest` - always specify exact versions (e.g., `alpine:3.19`, `ubuntu:22.04`) +- [ ] **User specification**: Use `--user $PUID:$PGID` when creating files in user directories to ensure proper permissions +- [ ] **Idempotent operations**: Commands should be safe to run multiple times +- [ ] **No hardcoded credentials**: Use system variables like `$PCS_DEFAULT_PASSWORD` + Example: ```yaml x-casaos: pre-install-cmd: | docker run --rm -v /DATA/AppData/filebrowser/db/:/db filebrowser/filebrowser:v2.32.0 config init --database /db/database.db && docker run --rm -v /DATA/AppData/filebrowser/:/data ubuntu:22.04 chown -R $PUID:$PGID /data && - docker run --rm -v /DATA/AppData/filebrowser/db/:/db filebrowser/filebrowser:v2.32.0 users add admin $default_pwd --perm.admin --database /db/database.db + docker run --rm -v /DATA/AppData/filebrowser/db/:/db filebrowser/filebrowser:v2.32.0 users add admin $PCS_DEFAULT_PASSWORD --perm.admin --database /db/database.db ``` **Common use cases:** @@ -324,117 +439,124 @@ x-casaos: - Generate certificates or keys - Prepare the environment with sensible defaults -#### NSL Router Integration (Web UI Access) +#### Caddy Integration (Web UI Access) -The Yundera AppStore uses the NSL Router (mesh-router) system to provide clean HTTPS URLs for your applications. The mesh router automatically generates subdomains based on your compose configuration. +The Yundera AppStore uses Caddy reverse proxy with Docker labels for automatic HTTPS routing. Apps are accessible via free nsl.sh subdomains (e.g., `https://appname-username.nsl.sh`). -**How NSL Router Works:** -- The mesh router runs on nsl.sh domains and provides subdomain routing to Yundera users -- Each user gets a subdomain like `username.nsl.sh` -- Applications are accessible via clean URLs without port numbers +**How It Works:** +- Caddy watches Docker containers for specific labels +- Labels define the subdomain prefix and backend port +- Caddy automatically handles HTTPS certificates and routing +- nsl.sh provides free subdomains for all Yundera users -**URL Generation Pattern:** -``` -https://[port]-appname-username.nsl.sh/ +**Label Format:** +```yaml +labels: + - "caddy=-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams }}" ``` -**Compose File Requirements for NSL Router:** -- Use `expose` instead of `ports` for web UI services -- Set `webui_port` to port 80 when possible (recommended for clean URLs) -- Other ports are supported but will include the port in the URL -- The router automatically handles HTTPS termination and routing - -**Example - Before NSL Router:** -``` -http://server-ip:2283/ # Direct port access -``` +**Compose File Requirements:** +- Use `expose` to expose the web UI port (required for Caddy discovery) +- Add Caddy labels to the main web UI service only +- Use `${APP_DOMAIN}` variable (resolves to `username.nsl.sh` in production) -**Example - With NSL Router:** +**Example - Basic Caddy Configuration:** ```yaml services: immich: image: altran1502/immich-server:v1.135.3 expose: - - 80 # Expose port 80 internally + - 80 # Expose port for Caddy discovery + labels: + - "caddy=immich-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams 80}}" environment: - IMMICH_PORT: 80 # Configure app to use port 80 - + IMMICH_PORT: 80 + x-casaos: main: immich - webui_port: 80 # Must match exposed port + webui_port: 80 ``` -**Result:** `https://immich-username.nsl.sh/` (clean URL, no port numbers) +**Result:** `https://immich-username.nsl.sh/` -**Alternative - Non-80 Port Example:** +**Example - Non-Port-80 Service:** ```yaml services: - grafana: - image: grafana/grafana:latest + duplicati: + image: linuxserver/duplicati:latest expose: - - 3000 # Expose port 3000 internally - environment: - GF_SERVER_HTTP_PORT: 3000 - + - 8200 # Expose the service port + labels: + - "caddy=duplicati-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams 8200}}" + x-casaos: - main: grafana - webui_port: 3000 # Must match exposed port + main: duplicati + webui_port: 8200 ``` -**Result:** `https://3000-grafana-username.nsl.sh/` (includes port in URL) +**Result:** `https://duplicati-username.nsl.sh/` **Port Selection Guidelines:** -- **Port 80**: Clean URLs without port numbers (recommended) -- **Other ports**: Accessible but URL includes port prefix -- **Standard ports**: Use application defaults when port 80 conflicts with app requirements +- Configure applications to use port 80 when possible +- Any port works with Caddy - just match the `expose` and label port values +- The URL remains clean regardless of the backend port -The mesh router handles: -- HTTPS certificate management +Caddy handles: +- Automatic HTTPS certificate management (Let's Encrypt) - Subdomain routing to the correct container -- VPN-secured communication between router and containers -- Port-based subdomain generation for non-80 ports +- Load balancing and health checks +- WebSocket proxying -**Web UI Requirements (all three must be configured together):** -- The main service must `expose` the web UI port (using `expose`, not necessarily `ports`) +**Web UI Requirements (all must be configured together):** +- The main service must `expose` the web UI port +- Add Caddy labels to the service with `caddy=-${APP_DOMAIN}` and `caddy.reverse_proxy` - The `webui_port` field must match the exposed port number -- The `main` field must reference a valid service name under `services` +- The `main` field must reference the service with Caddy labels **Important Notes:** -- Only one web UI domain is supported per app (even with multiple containers) -- HTTPS unwrapping is handled automatically by nsl.sh mesh router - no certificate management needed at container level -- Other ports can still be bound directly to the public IP for non-web services -- the main app name and hostname should be a simple name without spaces or special characters, as it will be used in the URL. +- Add Caddy labels only to the main web UI service (not to database or backend services) +- The service name in the `caddy=` label should match the `main` field in x-casaos +- Use `${APP_DOMAIN}` for portability across different deployments +- The app name should be simple without spaces or special characters -**Example Configuration:** +**Example Multi-Service Configuration:** ```yaml services: database: image: postgres:13 - # Database service - no web UI - + # Database service - no Caddy labels needed + webui-service: image: myapp:latest expose: - 8080 # Must expose the web UI port + labels: + - "caddy=myapp-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams 8080}}" ports: - "9000:9000" # Direct port binding for API or other services depends_on: - database x-casaos: - main: webui-service # References the service with web UI - webui_port: 8080 # Must match the exposed port above + main: webui-service # References the service with Caddy labels + webui_port: 8080 # Must match the exposed port ``` #### System Variables CasaOS automatically provides several system variables for your compose files: -** Variables:** -- `$default_pwd`: A secure default password generated by CasaOS for applications requiring authentication -- `$domain`: The domain or subdomain mapped to this container for web UI access -- `$public_ip`: The public IP address used for port binding announcements and external access +**Available Variables:** +- `$PCS_DEFAULT_PASSWORD`: A secure default password generated by CasaOS for applications requiring authentication +- `$PCS_DOMAIN`: The domain (without https://) mapped to this container for web UI access +- `$PCS_PUBLIC_IP`: The public IP address used for port binding announcements and external access +- `$PCS_DATA_ROOT`: The data root directory (always `/DATA`) +- `$PCS_EMAIL`: Admin email in the format `admin@DOMAIN` - `$AppID`: The application name/ID - `$PUID/$PGID`: User/Group IDs for proper file permissions - `$TZ`: System timezone @@ -442,9 +564,11 @@ CasaOS automatically provides several system variables for your compose files: **Example Usage:** ```yaml environment: - - PASSWORD=$default_pwd - - DOMAIN=$domain - - PUBLIC_IP=$public_ip + - PASSWORD=$PCS_DEFAULT_PASSWORD + - DOMAIN=$PCS_DOMAIN + - PUBLIC_IP=$PCS_PUBLIC_IP + - EMAIL=$PCS_EMAIL + - DATA_ROOT=$PCS_DATA_ROOT - PUID=$PUID - PGID=$PGID - TZ=$TZ diff --git a/README.md b/README.md index 8bb8d5e..226b4db 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Yundera CasaOS 3rd-Party AppStore ## About -This AppStore provides a curated list of applications compatible with CasaOS running on Yundera servers. The apps are specifically configured to work with the nsl.sh mesh router service and are accessible over HTTPS by default. +This AppStore provides a curated list of applications compatible with CasaOS running on Yundera servers. The apps are specifically configured to work with Caddy reverse proxy and nsl.sh free subdomains, accessible over HTTPS by default. ### Key Differences from Official CasaOS AppStore Regular CasaOS app URL: @@ -11,18 +11,17 @@ Yundera app URL: ```https://memo-demo.nsl.sh``` All apps are designed to run on CasaIMG, a dockerized version of CasaOS. -All apps are accessible over HTTPS by default. -All apps are tested on Yundera servers using a nsl.sh routing domain. +All apps are accessible over HTTPS by default via Caddy reverse proxy. +All apps are tested on Yundera servers using nsl.sh routing domains. ## Related Projects -- [CasaIMG](https://github.com/yundera/casa-img) - Docker-based CasaOS image manager with mesh router compatibility -- [Mesh-Router](https://github.com/yundera/mesh-router) - Domain management system for containerized applications, integrated with CasaIMG +- [CasaIMG](https://github.com/yundera/casa-img) - Docker-based CasaOS image manager with Caddy integration ## Sponsors -* **Yundera** - [yundera.com](https://yundera.com) +* **Yundera** - [yundera.com](https://yundera.com) Easy to use cloud server for open source container applications -* **NSL.SH** - [nsl.sh](https://nsl.sh) - Free domain provider for open source projects +* **NSL.SH** - [nsl.sh](https://nsl.sh) + Free subdomain provider for open source projects ## Contributing We welcome contributions to help grow this AppStore: