diff --git a/Apps/NoteDiscovery/docker-compose.yml b/Apps/NoteDiscovery/docker-compose.yml new file mode 100644 index 0000000..c894a8f --- /dev/null +++ b/Apps/NoteDiscovery/docker-compose.yml @@ -0,0 +1,216 @@ +name: notediscovery + +services: + notediscovery: + image: ghcr.io/gamosoft/notediscovery:0.16.3 + container_name: notediscovery + restart: unless-stopped + user: "0:0" + networks: + - pcs + expose: + - "80" + labels: + - "caddy=notediscovery-${APP_DOMAIN}" + - "caddy.reverse_proxy={{upstreams 80}}" + volumes: + - /DATA/AppData/$AppID/data/:/app/data + environment: + TZ: $TZ + PORT: 80 + AUTHENTICATION_ENABLED: true + AUTHENTICATION_PASSWORD: $PCS_DEFAULT_PASSWORD + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:80/health')"] + interval: 60s + timeout: 3s + retries: 3 + start_period: 5s + deploy: + resources: + limits: + memory: 512M + cpu_shares: 50 + +networks: + pcs: + external: true + +x-casaos: + architectures: + - amd64 + - arm64 + main: notediscovery + webui_port: 80 + author: Yundera Team + category: Documents + developer: gamosoft + store_app_id: notediscovery + icon: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/NoteDiscovery/icon.png + screenshot_link: + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/NoteDiscovery/screenshot-1.png + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/NoteDiscovery/screenshot-2.png + - https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/NoteDiscovery/screenshot-3.png + thumbnail: https://cdn.jsdelivr.net/gh/Yundera/AppStore@main/Apps/NoteDiscovery/screenshot-1.png + description: + en_us: | + **Your private, self-hosted knowledge base** + + NoteDiscovery is a lightweight, privacy-first note-taking app. Your notes are stored as plain markdown files — no vendor lock-in, no data sent to external services. + + **Key Features:** + - Plain markdown files with no vendor lock-in + - Graph view for visualizing connected notes + - Instant full-text search across all notes + - LaTeX/MathJax mathematical equation support + - Mermaid diagram creation + - HTML export functionality + - Built-in password protection + - Dark and light mode + + **Perfect for:** Anyone who wants a private, fast, and simple knowledge base with full data ownership. + ko_kr: | + **프라이빗 셀프 호스팅 지식 베이스** + + NoteDiscovery는 가볍고 프라이버시 우선의 노트 앱입니다. 노트는 일반 마크다운 파일로 저장되어 벤더 종속 없이, 외부 서비스로 데이터가 전송되지 않습니다. + + **주요 기능:** + - 벤더 종속 없는 일반 마크다운 파일 저장 + - 연결된 노트를 시각화하는 그래프 뷰 + - 모든 노트에 걸친 즉각 전문 검색 + - LaTeX/MathJax 수학 수식 지원 + - Mermaid 다이어그램 생성 + - HTML 내보내기 기능 + - 내장 비밀번호 보호 + - 다크 및 라이트 모드 + + **이런 분께 완벽해요:** 완전한 데이터 소유권을 가진 프라이빗하고 빠르며 심플한 지식 베이스를 원하는 모든 분. + zh_cn: | + **您的私有自托管知识库** + + NoteDiscovery 是一个轻量级、隐私优先的笔记应用。您的笔记以纯 Markdown 文件存储——无供应商锁定，无数据发送到外部服务。 + + **主要功能：** + - 纯 Markdown 文件存储，无供应商锁定 + - 图形视图可视化连接的笔记 + - 跨所有笔记的即时全文搜索 + - LaTeX/MathJax 数学公式支持 + - Mermaid 图表创建 + - HTML 导出功能 + - 内置密码保护 + - 深色和浅色模式 + + **非常适合：** 任何想要拥有完全数据所有权的私有、快速、简单知识库的人。 + fr_fr: | + **Votre base de connaissances privée et auto-hébergée** + + NoteDiscovery est une application de prise de notes légère et axée sur la confidentialité. Vos notes sont stockées sous forme de fichiers Markdown — sans verrouillage fournisseur, sans envoi de données à des services externes. + + **Fonctionnalités principales :** + - Fichiers Markdown sans verrouillage fournisseur + - Vue graphique pour visualiser les notes connectées + - Recherche plein texte instantanée dans toutes les notes + - Support des équations mathématiques LaTeX/MathJax + - Création de diagrammes Mermaid + - Fonctionnalité d'export HTML + - Protection par mot de passe intégrée + - Mode sombre et clair + + **Parfait pour :** Toute personne souhaitant une base de connaissances privée, rapide et simple avec une propriété complète des données. + es_es: | + **Tu base de conocimiento privada y auto-alojada** + + NoteDiscovery es una aplicación de notas ligera y centrada en la privacidad. Tus notas se almacenan como archivos Markdown — sin bloqueo de proveedor, sin envío de datos a servicios externos. + + **Características principales:** + - Archivos Markdown sin bloqueo de proveedor + - Vista de grafo para visualizar notas conectadas + - Búsqueda de texto completo instantánea en todas las notas + - Soporte de ecuaciones matemáticas LaTeX/MathJax + - Creación de diagramas Mermaid + - Funcionalidad de exportación HTML + - Protección por contraseña integrada + - Modo oscuro y claro + + **Perfecto para:** Cualquiera que quiera una base de conocimiento privada, rápida y simple con propiedad completa de los datos. + tagline: + en_us: Private self-hosted knowledge base with markdown notes + ko_kr: 마크다운 노트 기반 프라이빗 셀프 호스팅 지식 베이스 + zh_cn: 基于 Markdown 笔记的私有自托管知识库 + fr_fr: Base de connaissances privée auto-hébergée avec notes Markdown + es_es: Base de conocimiento privada auto-alojada con notas Markdown + title: + en_us: NoteDiscovery + tips: + before_install: + en_us: | + **Getting Started:** + + 1. After installation, visit your NoteDiscovery instance + 2. Log in with password: `$PCS_DEFAULT_PASSWORD` + 3. Start creating your first note + + **Features:** + - Notes are stored as plain markdown files + - Graph view to visualize note connections + - Full-text search across all notes + - LaTeX, Mermaid diagrams supported + + **Note:** Password protection is enabled by default. + ko_kr: | + **시작하기:** + + 1. 설치 후 NoteDiscovery 인스턴스를 방문하세요 + 2. 비밀번호로 로그인: `$PCS_DEFAULT_PASSWORD` + 3. 첫 번째 노트 작성을 시작하세요 + + **기능:** + - 노트는 일반 마크다운 파일로 저장 + - 노트 연결을 시각화하는 그래프 뷰 + - 모든 노트에 걸친 전문 검색 + - LaTeX, Mermaid 다이어그램 지원 + + **참고:** 비밀번호 보호가 기본으로 활성화되어 있습니다. + zh_cn: | + **开始使用：** + + 1. 安装后，访问您的 NoteDiscovery 实例 + 2. 使用密码登录：`$PCS_DEFAULT_PASSWORD` + 3. 开始创建您的第一个笔记 + + **功能：** + - 笔记以纯 Markdown 文件存储 + - 图形视图可视化笔记连接 + - 跨所有笔记的全文搜索 + - 支持 LaTeX、Mermaid 图表 + + **注意：** 密码保护默认已启用。 + fr_fr: | + **Commencer :** + + 1. Après l'installation, visitez votre instance NoteDiscovery + 2. Connectez-vous avec le mot de passe : `$PCS_DEFAULT_PASSWORD` + 3. Commencez à créer votre première note + + **Fonctionnalités :** + - Notes stockées sous forme de fichiers Markdown + - Vue graphique pour visualiser les connexions + - Recherche plein texte dans toutes les notes + - Support LaTeX, diagrammes Mermaid + + **Note :** La protection par mot de passe est activée par défaut. + es_es: | + **Comenzar:** + + 1. Después de la instalación, visite su instancia de NoteDiscovery + 2. Inicie sesión con la contraseña: `$PCS_DEFAULT_PASSWORD` + 3. Comience a crear su primera nota + + **Características:** + - Notas almacenadas como archivos Markdown + - Vista de grafo para visualizar conexiones + - Búsqueda de texto completo en todas las notas + - Soporte para LaTeX, diagramas Mermaid + + **Nota:** La protección por contraseña está activada por defecto. + index: / diff --git a/Apps/NoteDiscovery/icon.png b/Apps/NoteDiscovery/icon.png new file mode 100644 index 0000000..5b67f4b Binary files /dev/null and b/Apps/NoteDiscovery/icon.png differ diff --git a/Apps/NoteDiscovery/screenshot-1.png b/Apps/NoteDiscovery/screenshot-1.png new file mode 100644 index 0000000..7f4aa43 Binary files /dev/null and b/Apps/NoteDiscovery/screenshot-1.png differ diff --git a/Apps/NoteDiscovery/screenshot-2.png b/Apps/NoteDiscovery/screenshot-2.png new file mode 100644 index 0000000..20327ab Binary files /dev/null and b/Apps/NoteDiscovery/screenshot-2.png differ diff --git a/Apps/NoteDiscovery/screenshot-3.png b/Apps/NoteDiscovery/screenshot-3.png new file mode 100644 index 0000000..ac6efe8 Binary files /dev/null and b/Apps/NoteDiscovery/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: