# Technical Documentation: beclab/docs > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/beclab/docs) ### Overview (README.md) # Olares Docs ## Run ```shell npm install npm run docs:dev ``` Open Browser at http://localhost:5173/docs/ --- ### Index (`docs/index.md`) --- # https://vitepress.dev/reference/default-theme-home-page layout: home hero: name: "Olares" text: "Let people own their data again" actions: - theme: brand text: What is Olares? link: /manual/feature-overview.html - theme: alt text: Get Started link: /manual/get-started/ - theme: alt text: GitHub link: https://github.com/beclab/olares features: - icon: 📝 title: Self-Hosted details: A protocol-based, permissionless application ecosystem - icon: 📝 title: Security details: Enterprise-grade security solution that works out of the box - icon: 📝 title: Collaboration details: Self-hosted your productivity platform for team collaboration - icon: 📝 title: Local AI details: Redefines the Personalized AI assistant --- --- ### Manual Feature Overview (`docs/manual/feature-overview.md`) # Feature comparison :::tip Legend - 🚀: **Auto**, indicates that the system completes the task automatically. - ✅: **Yes**, indicates that users without a developer background can complete the setup through the product's UI prompts. - 🛠️: **Manual Configuration**, indicates that even users with an engineering background need to refer to tutorials to complete the setup. - ✖️: **No**, indicates that the feature is not supported. ::: | | Olares | Synology | TrueNAS | CasaOS | Unraid | |---------------------------|------------------------------------------------------------------------------------------------------------|---------------------------------------------|---------------------------------------------|-------------------------|-----------------------------------------------| | Multi-node | ✅ | ✖️ | ✅ | ✖️ | ✖️ | | Build-in apps | ✅ (Rich desktop apps) | ✅ (Rich desktop apps) | ✖️ (CLI) | ✅ (Simple desktop apps) | ✅ (Dashboard) | | Free domain name | ✅ | ✅ | ✖️ | ✖️ | ✖️ | | Auto SSL certificate | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | | Reverse proxy | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | | VPN management | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | Graded app entrance | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | Multi-user management | ✅ User management
🚀 Resource isolation | ✅ User management
🛠️ Resource isolation | ✅ User management
🛠️ Resource isolation | ✖️ | ✅ User management
🛠️ Resource isolation | | Single login for all apps | 🚀 | ✖️ | ✖️ | ✖️ | ✖️ | | Cross-node storage | 🚀 (Juicefs+
MinIO) | ✖️ | ✖️ | ✖️ | ✖️ | | Database solution | 🚀 (Built-in cloud-native solution) | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | Disaster recovery | 🚀 (MinIO's [**Erasure Coding**](https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html)) | ✅ RAID | ✅ RAID | ✅ RAID | ✅ Unraid Storage | | Backup | ✅ App Data
✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data | | App sandboxing | ✅ | ✖️ | ✖️ (K8S's namespace) | ✖️ | ✖️ | | App ecosystem | ✅ (Official + third-party) | ✅ (Majorly official apps) | ✅ (Official + third-party submissions) | ✅ Majorly official apps | ✅ (Community app market) | | Developer friendly | ✅ IDE
✅ CLI
✅ SDK
✅ Doc | ✅ CLI
✅ SDK
✅ Doc | ✅ CLI
✅ Doc | ✅ CLI
✅ Doc | ✅ Doc | | Local LLM hosting | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | Local LLM app development | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | Client platforms | ✅ Android
✅ iOS
✅ Windows
✅ Mac
✅ Chrome Plugin | ✅ Android
✅ iOS | ✖️ | ✖️ | ✖️ | | Client functionality | ✅ (All-in-one client app) | ✅ (14 separate client apps) | ✖️ | ✖️ | ✖️ | --- ### Space Index (`docs/space/index.md`) --- description: Discover Olares Space platform for managed cloud hosting of Olares instances. Explore infrastructure services, host services, account management, and billing features for efficient cloud deployment. --- # Olares Space overview Olares Space is the fully managed offering of Olares on public clouds. It provides two categories of services: - **Infrastructure service** – Manages data backup, custom domain configuration, reverse proxy, and shared GPU resources. - **Host service** – Hosts and manage Olares instances on public cloud platforms. Olares Space account is associated with your Olares IDs or DIDs. You can log in to Olares Space by scanning QR code using LarePass. This section walks you through usages of Olares Space, covering: - [Log in to/off Olares Space](manage-accounts.md) - [Host Olares](create-olares.md) - [Manage Olares](manage-olares.md) - [Host custom domains](host-domain.md) - [Manage organization domains](manage-domain.md) - [Back up & Restore Olares](backup-restore.md) - [Usage and Billing](billing.md) --- ### Use Cases Index (`docs/use-cases/index.md`) --- description: Explore practical use cases of Olares, showcasing how to leverage its features for AI workflows, creative tools, and self-hosted applications. Unlock the full potential of Olares in your environment. --- # Use cases and tutorials While other guides tell you "what" and "how" with Olares, this section dives into the real-world use cases that reveal the full potential of Olares. From running AI models to building seamless workflows across your self-hosted services, these hands-on guides help you accomplish specific tasks and implement complete, practical solutions using your installed applications. --- ### Zh Index (`docs/zh/index.md`) --- # https://vitepress.dev/reference/default-theme-home-page layout: home hero: name: "Olares" text: "Let people own their data again" actions: - theme: brand text: What is Olares? link: /manual/feature-overview.html - theme: alt text: Get Started link: /manual/get-started/ - theme: alt text: GitHub link: https://github.com/beclab/olares features: - icon: 📝 title: Self-Hosted details: A protocol-based, permissionless application ecosystem - icon: 📝 title: Security details: Enterprise-grade security solution that works out of the box - icon: 📝 title: Collaboration details: Self-hosted your productivity platform for team collaboration - icon: 📝 title: Local AI details: Redefines the Personalized AI assistant --- --- ### Developer Develop Index (`docs/developer/develop/index.md`) # Develop Olares application Developing applications on Olares is not much different from regular website development. Once you learn a few basic Olares concepts, you can start creating applications on his platform. - [Core Concepts of Olares](../../manual/concepts/index.md) - [Understanding the Format of Olares Application Chart](./package/chart.md) - [The structure of the Olares Application Chart](./package/chart.md) - [Configuration guide and field descriptions of `OlaresManifest.yaml`](./package/manifest.md) - [Extensions field to Helm in Olares](./package/extension.md) - [Exploring Our Tutorials](./tutorial/) - [Learn about Devbox, an Olares Development Tool](./tutorial/studio) - [Creating your first application](./tutorial/note/) - [Exploring Advanced Concepts](./advanced/) - [Submitting Applications to the Olares Market](./submit/) --- ### Developer Install Index (`docs/developer/install/index.md`) --- description: Technical overview of Olares deployment including system architecture, setup processes, environment configuration, CLI capabilities and version management. Key concepts for developers working with Olares. --- # Olares installation deep-dive This section provides in-depth information, command references, and instructions to help you explore, learn, and customize your Olares installation. - [Olares installation overview](installation-process.md): Learn how Olares is installed from the perspectives of overall architecture and core components. - [Olares installation breakdown](installation-process.md): Explore the Olares installation process in detail, broken down into four key phases. - [Olares Home introduction](olares-home.md): Understand the structure of the base installation directory. - [Olares environment variables reference](environment-variables.md): Find the right environment variables for you to customize the installation. - [Olares CLI reference](./index.md): Uses the Olares CLI for advanced customization and troubleshooting during installation. - [Olares versioning](versioning.md): Learn versioning rules, release types, branch management practices, and upgrade guidelines of Olares. --- ### Developer Install Installation Overview (`docs/developer/install/installation-overview.md`) --- outline: [2, 3] description: Core architecture of Olares deployment across native system layer, Kubernetes orchestration and containerized services. Technical insights into how Olares layers interact. --- # Olares installation architecture This document provides a high-level overview of the Olares installation process, focusing on its overall architecture and core components. It is intended for system administrators and developers who need a foundational understanding of how Olares operates and is installed. ## Three layers of Olares installation The Olares installation is structured into three key layers: - **Native layer**: Manages Linux system configurations and installs essential environment dependencies. - **Container orchestration layer**: Deploys the Kubernetes cluster to enable automated service management and scaling. - **Containerization layer**: Launches containerized core system services and user applications, providing the final runtime environment. The installation process is managed by the `olares-cli` tool. This command-line tool orchestrates the installation, configuration, and lifecycle management of all components. ::: tip To understand the detailed installation process phase-by-phase, refer to [Olares installation breakdown](installation-process.md). ::: ## Native layer The Olares installation process begins at the native layer, ensuring that the underlying Linux environment supports distributed storage, container runtimes, and Kubernetes cluster management. This layer's configuration includes core Linux system settings, file system initialization, container runtime installation, and deployment of critical system services. ### Environment configuration The installation first configures the basic Linux installation environment. This includes setting up Domain Name System (DNS), Secure Shell (SSH), and Network Time Protocol (NTP) services to ensure time synchronization and remote management capabilities. Additionally, necessary dependencies such as the GNU Compiler Collection (GCC) and Network Tools (net-tools) are installed to ensure a robust runtime environment. ### File system configuration The root file system (rootfs) is used to store and access system core components and user data. Olares supports the following two file systems based on deployment needs: - **LocalFS** (default): Uses the local Linux disk for storage. It is ideal for single-node deployments that require high data throughput without the need for network sharing. - **JuiceFS**: Provides a distributed file system for multi-node cluster. File data are stored in locally installed MinIO instances or remote storage buckets such as Amazon S3. This setup allows different storage nodes to share a unified storage view. :::tip Enable JuiceFS JuiceFS and MinIO are not installed by default. To enable them, set the necessary [environment variables](environment-variables.md#juicefs) or use `olares-cli` with JuiceFS-specific flags. ::: ### Container runtime: containerd Olares uses containerd, a lightweight container runtime, for containerized deployments. Its features include: - **Container image management**: - Downloads packaged container images from the Content Delivery Network (CDN) - Imports them into containerd during the "prepare" phase - Starts the images as container processes during the "install" phase - **Container lifecycle management**: Starts, stops, restarts, and monitors containerized application services. ::: tip Compatibility issue If containerd is already installed on your machine (for example, as part of Docker), it may cause compatibility issues with the containerd used by Olares. Please uninstall the existing containerd before installing Olares. ::: ### System daemon: olaresd olaresd is the system daemon that runs in the background, providing essential management functionalities such as: - **Automated configuration updates**: Automatically adjusts configurations when system changes (e.g. IP changes) are detected. - **Remote system management**: Executes remote system operations, such as Olares installation and activation, based on requests issued from the LarePass client or `olares-cli`. ### CUDA support To enable GPU acceleration for local AI models and applications, Olares supports automatic installation of the CUDA toolkit and drivers through [`olares-cli`](./cli-1.11/gpu.md). ## Container orchestration layer The container orchestration layer integrates system components into an efficient runtime environment using Kubernetes. ### Roles of Kubernetes Kubernetes serves as the backbone of the container orchestration layer, providing automated deployment, operation, scaling, and management of multi-component services. Compared to tools like Docker Compose or Docker Swarm, Kubernetes offers: - High scalability and production-grade reliability. - Robust community support and a rich ecosystem for integrating applications via Helm Charts, Operators, and Custom Resource Definitions (CRDs). ### Kubernetes options in Olares Olares supports the following Kubernetes setups: - **K3s** (default): A lightweight Kubernetes distribution optimized for resource efficiency on local hardware. - **Kubernetes**: The full-featured Kubernetes distribution for advanced or custom deployments. - **minikube** (macOS only): A tool that sets up a single-node Kubernetes cluster, ensuring consistent features and user experience. ## Containerization layer The containerization layer is where Olares' components and applications come together to provide the system's full functionality. All Olares components and user applications run within containers, with the full lifecycle managed via Kubernetes. This ensures that the system remains efficient, stable, and scalable. Once Olares is installed and activated, you can view the running containers through a graphical user interface provided by the Control Hub app: {width=90%} ## Learn more - [Olares installation breakdown](installation-process.md) - [Olares Home](olares-home.md) - [Olares CLI](../install/cli-1.11/olares-cli.md) - [Olares environment variables](environment-variables.md) --- ### Manual Best Practices Index (`docs/manual/best-practices/index.md`) --- description: In-depth guides and proven best practices to help you get the most out of Olares. --- # Beyond the basics: Olares best practices and advanced guides This section offers in-depth guides and proven best practices to help you get the most out of Olares. Whether you're optimizing performance, securing your environment, or customizing advanced features, these resources go beyond initial setup to support real-world scenarios and power-user workflows. - [Configure a custom domain for your Olares](set-custom-domain.md) - [Install a multi-node Olares cluster](install-olares-multi-node.md) - [Build your knowledge hub with Wise](organize-content.md) --- ### Manual Concepts Index (`docs/manual/concepts/index.md`) --- description: Core concepts documentation of Olares system, covering architecture design, identity authentication, application management, network configuration and data security fundamentals for developers. --- # Overview The Concepts section helps you learn about the parts of the Olares system and obtain a deeper understanding of how Olares works. Read this section as needed to: - Develop applications for Olares - Manage system deployments - Troubleshoot issues - Optimize system performance Understand Olares with the following concepts: - [Architectural components](architecture.md) - [Olares ID](./olares-id.md) - [Account](./account.md) - [Application](./application.md) - [Network](./network.md) - [Data](./data.md) - [Secrets](./secrets.md) --- ### Manual Get Started Index (`docs/manual/get-started/index.md`) --- description: Choose your path to begin using Olares for personal or team use. --- # Get started Welcome to Olares! This guide will help you quickly set up and start using Olares on your preferred platform. ::: tip If you prefer to try the cloud version of Olares instead of self-hosting, refer to the [Olares Space documentation](../../space/). :::

First time using Olares?

Learn how to create an Olares ID, and get your Olares up and running.

→

Already have an Olares?

Explore our comprehensive how-to guide covering every aspect of Olares.

→

Ready to get productive with Olares?

Explore our use cases and tutorials to see how Olares can streamline your workflow and unlock new possibilities.

→
--- ### Manual Larepass Index (`docs/manual/larepass/index.md`) --- outline: [2, 3] --- # LarePass documentation LarePass is the official cross-platform client software for Olares. It acts as a secure bridge between users and their Olares systems, enabling seamless access, identity management, file synchronization, and secure data workflows across all your devices, whether you're on mobile, desktop, or browser. ## Key features ### Account & identity management Create and manage your Olares ID, connect integrations with other services, and back up your credentials securely. - [Create an Olares ID](create-account.md) - [Back up mnemonics](back-up-mnemonics.md) - [Set or reset local password](back-up-mnemonics.md#set-up-local-password) - [Manage integrations](integrations.md) ### Secure file access & sync Access and sync your Olares files across devices. - [Manage files with LarePass](manage-files.md) - [Sync and share files](sync-share.md) ### Device & network management Activate and manage Olares devices, and securely connect to Olares via LarePass VPN. - [Activate your Olares device](activate-olares.md) - [Log in to Olares with 2FA](activate-olares.md#two-factor-verification-with-larepass) - [Manage Olares](manage-olares.md) - [Switch networks](manage-olares.md#switch-from-wired-to-wireless-network) - [Enable VPN for remote access](private-network.md) ### Password & secret management Use Vault to autofill credentials, store passwords, and generate 2FA codes across devices. - [Autofill passwords](/manual/larepass/autofill.md) - [Generate 2FA codes](/manual/larepass/two-factor-verification.md) ### Knowledge collection Use LarePass to collect web content and follow RSS feeds. - [Collect content via LarePass extension](manage-knowledge.md#collect-content-via-the-larepass-extension) - [Subscribe to RSS feeds](manage-knowledge.md#subscribe-to-rss-feeds) --- ## Download and install LarePass Get the latest version for your device at the [LarePass website](https://www.olares.com/larepass). ### Install the LarePass browser extension :::tip Quick access After installation, pin the LarePass extension from Chrome’s extension menu for one-click access. ::: --- ### Manual Olares Index (`docs/manual/olares/index.md`) --- description: Learn how to use Olares system applications with step-by-step guides covering personalization, application management, file handling, security setup, and team collaboration features. Updated regularly with the latest Olares functionality. --- # Olares system applications Olares system applications are a core component of the Olares ecosystem, pre-installed on your Olares to provide a fundamental yet powerful set of tools. These applications are designed to help you efficiently manage files and applications, organize knowledge, configure system, and accomplish many other daily tasks. Understanding the functions and value of these system applications will enable you to fully leverage Olares' potential, creating a personal cloud environment tailored to your personal needs. This document serves as your comprehensive guide to exploring Olares system applications, empowering you to better navigate your Olares system. ## What can you do with system applications? Explore the following guides to get the most out of Olares’s built-in apps: [**Navigate and customize your Desktop**](./desktop.md): Launch apps, organize your workspace, and search across Olares. [**Install and manage apps with Market**](./market.md): Discover, install, update, or remove apps and recommendation algorithms from an open permisionless application store. [**Store, sync, and access Files**](./files/): Upload, download, organize, and share files securely across devices with centralized storage and real-time synchronization. [**Secure and manage passwords with Vault**](./vault/): Store credentials, manage digital identities, and generate OTPs in a powerful, secure password management tool. [**Collect and curate knowledge with Wise**](./wise/): Collect, consume, and manage content from various platforms, get personalized recommendations, creating and maintaining your personal information hub. [**Configure and customize your Olares with Settings**](./settings/): Set up users, apps, network, integrations, security, appearance, backups, and more, all from one centralized interface. [**Monitor and control Olares environment with Control Hub**](./controlhub/): Monitor system status, manage application services, and fine-tune your Olares environment from a single console. [**Learn system status with Dashboard**](./resources-usage.md): View real-time resource usage and performance metrics in an easy-to-understand interface. [**Design your unique Olares Profile**](profile.md): Customize your personal homepage on Olares to reflect your identity and share with others. --- ### Zh Manual Feature Overview (`docs/zh/manual/feature-overview.md`) # 功能对比 :::tip 图例说明 - 🚀: **自动**，系统自动完成任务 - ✅: **支持**，非开发者也能通过产品界面提示完成设置 - 🛠️: **手动配置**，工程背景用户也需要参考教程完成设置 - ✖️: **不支持**，不具备该功能 ::: | | Olares | 群晖 | TrueNAS | CasaOS | Unraid | |-----------|-----------------------------------------------------------------------------------------------|--------------------------|--------------------|----------------|---------------------| | 多节点 | ✅ | ✖️ | ✅ | ✖️ | ✖️ | | 内置应用 | ✅ (丰富的桌面应用) | ✅ (丰富的桌面应用) | ✖️ (命令行) | ✅ (简单的桌面应用) | ✅ (控制面板) | | 免费域名 | ✅ | ✅ | ✖️ | ✖️ | ✖️ | | SSL 证书自动化 | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | | 反向代理 | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | | VPN 管理 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | 应用入口分级 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | 多用户管理 | ✅ 用户管理
🚀 资源隔离 | ✅ 用户管理
🛠️ 资源隔离 | ✅ 用户管理
🛠️ 资源隔离 | ✖️ | ✅ 用户管理
🛠️ 资源隔离 | | 应用统一登录 | 🚀 | ✖️ | ✖️ | ✖️ | ✖️ | | 跨节点存储 | 🚀 (Juicefs+
MinIO) | ✖️ | ✖️ | ✖️ | ✖️ | | 数据库方案 | 🚀 (内置云原生方案) | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | 容灾 | 🚀 (MinIO [**纠删码**](https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html)) | ✅ RAID | ✅ RAID | ✅ RAID | ✅ Unraid 存储 | | 备份 | ✅ 应用数据
✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | | 应用沙箱 | ✅ | ✖️ | ✖️ (K8S 命名空间) | ✖️ | ✖️ | | 应用生态 | ✅ (官方 + 第三方) | ✅ (主要是官方应用) | ✅ (官方 + 第三方提交) | ✅ 主要是官方应用 | ✅ (社区应用市场) | | 开发友好度 | ✅ IDE
✅ CLI
✅ SDK
✅ 文档 | ✅ CLI
✅ SDK
✅ 文档 | ✅ CLI
✅ 文档 | ✅ CLI
✅ 文档 | ✅ 文档 | | 本地大模型部署 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | 本地大模型应用开发 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | | 客户端平台 | ✅ 安卓
✅ iOS
✅ Windows
✅ Mac
✅ Chrome 插件 | ✅ 安卓
✅ iOS | ✖️ | ✖️ | ✖️ | | 客户端功能 | ✅ (一体化客户端) | ✅ (14个独立客户端) | ✖️ | ✖️ | ✖️ | --- ### Zh Space Index (`docs/zh/space/index.md`) --- description: Olares Space 是 Olares 在公有云上的全托管服务，支持数据备份、域名配置、反向代理和 GPU 资源管理，通过 LarePass 扫码登录以访问所有功能。 --- # Olares Space 概述 Olares Space 是 Olares 在公有云上的全托管服务，提供两大类服务： - **基础设施服务**：负责数据备份、自定义域名配置、反向代理和共享 GPU 资源管理 - **托管服务**：在公有云平台上托管和管理 Olares 实例 Olares Space 账号与你的 Olares ID 或 DID 关联。你可以通过 LarePass 扫描二维码登录 Olares Space。 本章节将为你介绍 Olares Space 的使用方法，包括： - [登录和退出 Olares Space](manage-accounts.md) - [托管 Olares](create-olares.md) - [管理 Olares](manage-olares.md) - [托管自定义域名](host-domain.md) - [管理组织域名](manage-domain.md) - [备份和恢复 Olares](backup-restore.md) - [使用量和计费](billing.md) --- ### Zh Use Cases Index (`docs/zh/use-cases/index.md`) --- description: 了解 Olares 在 AI 流程、创意工具和自托管应用中的实际用例，充分释放 Olares 的潜力。 --- # 使用场景与教程 本节聚焦于**真实场景**，帮助你充分挖掘 Olares 的强大功能。 从运行 AI 模型到在自托管服务间构建无缝工作流，这些动手教程将指导你完成具体任务，并利用已安装的应用实现完整、实用的解决方案。 --- ### Developer Contribute Olares Id Index (`docs/developer/contribute/olares-id/index.md`) --- # https://vitepress.dev/reference/default-theme-home-page layout: home hero: name: "Snowinning Protocol" text: "" tagline: Building a Self-Sovereign Internet actions: - theme: brand text: What is Snowinning link: /protocol/overview.md - theme: alt text: Vist GitHub link: https://github.com/beclab/terminus features: - title: Snowinning Protocol details: A decentralized identity and credit system that facilitates secure, trustless exchanges of information and value. - title: Smart Contract details: Snowinning Protocol's smart contract consists of DID Registry and the extended reputation systems based on DID. - title: Verifiable Credential (VC) details: Fully ratified W3C standard that work together with DIDs to enable trustless, secure interactions. --- --- ### Developer Contribute System App Overview (`docs/developer/contribute/system-app/overview.md`) # Develop System Application for Olares ::: tip Prerequisites Knowledge - Debugging third-party applications with **DevBox** - Developing applications with **DevBox** - Understanding the architecture and mechanisms of **Olares** ::: After a year and a half of work, the Olares team now uses **DevBox** for developing system applications. We will show you how to debug issues in the frontend code of **Desktop** using **DevBox**. 1. Create an application in DevBox 2. Configure [deployment.yaml](./deployment) 3. Configure [OlaresManifest.yaml](./olares-manifest) 4. Install the application 5. Configure [nginx.conf](./install) There are also some [other](./other) aspects to consider in development. --- ### Developer Develop Advanced Index (`docs/developer/develop/advanced/index.md`) # Advanced 1. [Olares CLI](cli/olares-cli.md) 2. [Olares Info](./terminus-info) 3. [Service Provider](./provider.md) 4. [AI](./ai.md) 5. [Cookie](./cookie.md) 6. [Database](./database.md) 7. [Account](./account.md) 8. [Market](./market.md) 9. [Websocket](./websocket.md) 10. [Files Upload](./file-upload.md) 11. [Secret](./secret.md) 12. [Kubesphere](./kubesphere.md) --- ### Developer Develop Submit Index (`docs/developer/develop/submit/index.md`) --- outline: [2, 3] --- # Submit Application ## Submitting Your Application **Brief Overview** 1. Test your application on Olares, create the Olares Application Chart according to [guideline](../package/chart.md). 2. Fork the official [application repository of Olares Market](https://github.com/beclab/apps). Add your application's chart. Create a **PR** to `beclab/apps:main`. 3. Wait for **GitBot** to check your PR. If needed, modify PR until it passes. 4. Once the PR is merged, your application is ready to launch. ### 1. Develop and test your application Before submitting an application, please ensure that it has been thoroughly tested on your Olares. - Use DevBox's dev-container to test and debug your application in a real online environment. [Learn more about DevBox](../tutorial/studio). - Use the [custom installation](/manual/olares/market.md#install-custom-applications) in the Market app for user testing. ### 2. Submit an application The submission of the application needs to be completed through a **Pull Request**. Here's how: - Fork the official [application repository of Olares Market](https://github.com/beclab/apps) and add your application's chart in your forked repository. - Create a `Draft PR` pointing to `beclab/apps:main`. - Please edit your PR title and text according to the template. - **PR Title** must in this format: [PR Type][FolderName][version]Title Content - `PR Type` includes: - NEW: Submit a new application - UPDATE: Update an already successfully merged application - REMOVE: Remove an already successfully merged application - SUSPEND: Suspend an already successfully merged application from distribution through the application store - `FolderName` is your Olares Application Chart name. It must adhere to the naming requirements in [chart specification](../package/chart.md). - `version` refers to your application chart's `Chart Version`, which needs to be consistent with the `version` field in `Chart.yaml` and metadata section of `OlaresManifest.yaml` - To prevent your PR from being incorrectly parsed or closed, please adhere to the following rules: - Your PR title must contain only one `PR Type`, `FolderName`, and `version`. - Your `PR Type` must be one of the predefined types. - A PR should only add or modify content under the `FolderName` declared in the PR title. - Only one Open PR or Draft PR can exist at a time with the same `FolderName`. - You must be one of the owners of the folder you wish to modify. Owners are listed in the `owners` file within the chart. If you're submitting a new application, your GitHub username should be included in the `owners` file. - During the Draft PR phase, you can continuously adjust your PR content and add new commits. Once everything is ready, click on the **'Ready for review'** button to submit the PR and call on **GitBot** to check. :::info NOTE The title and content of the PR are crucial for **GitBot**. Please adhere to the template specifications when filling them out. **GitBot** may automatically close any invalid PRs. ::: ### 3. Track your PR status - When your PR is labeled with `PR type`, it indicates that your PR title is valid. Please **do not modify the `PR Type` afterwards.** If it doesn't reflect your intentions, simply close it and create a new one. - You can track the progress of your PR through the status tags: - `waiting to submit`: your PR has an issue and requires further modification before merging. - `closed`: your PR is invalid or contains uncorrectable errors. - `waiting to merge`: Everything is progressing smoothly. Your PR has passed the check and is now awaiting auto-merge by the **GitBot**. - `merged`: your PR has been automatically merged into the `beclab/apps:main`. - If **GitBot** automatically closes your PR, please **do not reopen** it. This implies that the PR has irreparable issues, and **GitBot** had to terminate the check process. You can submit a new PR after making necessary modifications. - During the `waiting to submit` state, you can continue to submit commits to modify your application chart. **GitBot** will recheck the application chart files and update the PR status upon receiving a new commit. - Once your PR passes all checks, it will be automatically merged into the `beclab/apps:main`. The application will be listed on **Olares Market** after a while. - If you encounter any issues during the submission process, feel free to reach out to the Olares team or seek assistance from the community. ## Managing Your Application You can continue managing and maintaining your application by creating a Pull Request to `beclab/apps:main`. You can upgrade your application, modify its availability, or completely remove it from the **Olares Market**. The process of managing applications is similar to submission.You create a specific type of Pull Request, and GitBot takes care of the rest. Olares uses **special control files** in the root directory of application chart to manage the application's status. These **special control files** are empty files with specific suffix, such as `.suspend` and `.remove` :::info NOTE No ".suspend" or ".remove" files should be included in the initial submission. ::: ### Update When you need to update a published application, you need to create an `UPDATE` PR. **Please note:** - Whenever you make changes to your application chart, such as upgrade the program, update metadata, or change owner list, be sure to upgrade your chart version. - The chart version in the updated application chart must be ***greater than*** the current version in the repository. - No `.suspend` or `.remove` files included in the root directory of updated application chart. - The **Olares Market** does not offer version rollback. If there are any issues with your application, you need to submit a new version to fix it. - To avoid potential conflicts, we recommend syncing your fork and rebase the commits of PR to the latest main branch. ### Suspend If for any reason you want to temporarily disable your application's download and installation from the **Olares Market**, submit a `SUSPEND` PR. **Please note:** - The chart version in the submitted application chart must ***match*** the current version in the repository. - The root directory you submit should contain the `.suspend` file and should not contain the `.remove` file. - Once the suspend PR passes check and merges, the application store will stop listing your application. - Users who have already downloaded and installed the application can continue to use it after suspension. ### Remove If for any reason you want to remove your application from the **Olares Market**, submit a `REMOVE` PR. **Please note:** - Completely empty the files in the current application directory and add a `.remove` file to the root directory. - Once the remove PR passes check and merges, the application store will remove your application. - You will not be able to reuse the same directory or application chart name in the future. - Users who have already downloaded and installed the application can continue to use it after removal. ## Promoting Your Application Utilizing well-organized application descriptions, screenshots, and promotional images to highlight the features and functions of your application can help attract new users in the Market. Screenshots and previews can intuitively demonstrate the user experience, helping your application stand out. To add promotional images on the application detail page, include links to these assets in the `promoteImage` fields within the `spec` section of the `OlaresManifest.yaml` file. :::info **Assets Specifications for the Olares Market** - The application's **icon** must be in PNG or WEBP format, up to 512 KB, with a size of 256x256 px. - It is highly recommended to upload at least 2 **screenshots** for promotion. **Screenshots** must be in JPEG, PNG, or WEBP format, up to 8MB each, with a size of 1440x900 px. You can upload up to 8 **screenshots**. - If you wish to have your application featured in the store, a **featured image** is required. Add a link to this image in the `featuredImage` field within the `spec` section of the `OlaresManifest.yaml` file. The image must be in JPEG, PNG, or WEBP format, up to 8MB, with a size of 1440x900 px ::: ## Inviting Others to Collaborate There are two ways to invite others to develop Olares applications together: 1. Add others developer's GitHub usernames to the `owners` file. Each developer listed in `owners` can then fork the repository and submit their changes independently. 2. Add others as collaborators to your forked repository. In this case, you create the Pull Request as a representative, and all others can jointly commit to the branch that is planned to merge. --- ### Developer Develop Tutorial Index (`docs/developer/develop/tutorial/index.md`) # Tutorial Welcome to the Olares developer guides. These detailed tutorials offer a step-by-step guide on building an Olares Application from scratch. To get started, you can learn some basic concepts of Olares, such as: - [Olares architectural components](../../../manual/concepts/architecture.md) - [Olares Application Chart](../../develop/package/chart.md) - [Olares Extension on Helm](../package/extension.md) These fundamentals will help you grasp our development process more effectively. You can also [learn about DevBox](studio.md), a built-in app that Olares provides for developers to build Olares applications. If you're brand new to Olares development and want to jump straight into coding, start with the [**Create your first Olares app**](./note/index.md). This tutorial will step you through the process of building a small note application. --- ### Manual Olares Controlhub Index (`docs/manual/olares/controlhub/index.md`) --- outline: [2, 3] description: Understand Control Hub UI to manage applications, monitor resources, configure networking, and maintain system settings in Olares. --- # Manage Olares with Control Hub Control Hub is the console for Olares, providing developers and users with precise control over system operations and the underlying environment. This guide helps you understand Control Hub's interface and efficiently monitor your resources. ## Features and components Control Hub organizes your system resources and usages into three different groups: ### Olares Monitor the status of applications in three different views: - **Browse** (Application-centric view): Navigate through resource usage related to specific applications using a three-column layout for efficient resource location. - **Namespace** (User-centric view): Access detailed insights into per-user application resource consumption, with sorting and filtering capabilities. - **Pods**: Monitor pod status and resource consumption at the finest granularity. ### Resource View and manage Kubernetes system resources. - **Networks**: Monitor network security policies implemented in the system and the network connectivity of each namespace. - **CRDs**: Manages various custom resource declarations in the system. ### Middleware View the usage of various middleware services in Olares. --- ### Manual Olares Files Index (`docs/manual/olares/files/index.md`) --- description: Manage files efficiently in Olares with secure storage, seamless synchronization across devices, and centralized file management capabilities. --- # Manage files in Olares Olares's built-in Files app offers users a secure and efficient solution for file storage and synchronization, allowing access to various file types from any device or browser. It has the following advantages: * **Access anywhere**: View, download, or share files stored in Olares from any location using any device or browser. * **Seamless synchronization**: Ensures data remains up-to-date across all your devices. * **Centralized storage**: Simplifies information retrieval and integration, making it easier to access, manage, and update your data, whether personal documents or team-shared materials. ## Understand the interface The interface is similar to Windows Explorer or macOS Finder, allowing you to organize and access documents, images, videos, or any other files you own. It consists of three main components: * **Drive**: For storing files that don't require frequent synchronization or modifications. * **Sync**: For syncing files and directories across devices. * **Application**: For development and debugging purposes only. * **CloudDrive**: For mounting and accessing your cloud storage services including Google Drive, AWS S3, Tencent Cloud Object Storage (COS) ---

Basic file operations

Learn the fundamentals of file management in Olares.

Sync and share files

Learn how to keep files updated across devices, and how to share files with other Olares member.

Mount SMB

Learn how to mount and access SMB shared folders from NAS devices or network servers in Olares.

Mount cloud storage

Learn how to mount and access third party cloud storage services in Olares
--- ### Manual Olares Settings Index (`docs/manual/olares/settings/index.md`) --- description: Configure and manage Olares with Settings, your central hub for personalizing your experience, securing your environment, integrating essential services, and more. --- # Configure and manage Olares with Settings The Settings application in Olares provides a clean, intuitive interface for configuring and managing your system. It serves as the central hub for personalizing your experience, securing your environment, integrating services, and more. Settings is organized into the following sections: - Manage security – Manage login devices and system security settings. - Manage accounts – Create and manage users within your Olares cluster. - Manage applications – Monitor and configure application status and behavior. - Manage integrations – Connect Olares to external web services and tools. - Customize appearance – Set system language and background preferences. - Configure network – Set up FRP, VPN, and edit the hosts file. - Backup and restore – Create and manage backup and restore tasks for selected directories. - Update system – View system details and install updates. - Export system log – Generate and export system logs for diagnostics. --- ### Manual Olares Vault Index (`docs/manual/olares/vault/index.md`) --- description: Secure your sensitive data with Vault - a comprehensive password manager featuring end-to-end encryption, shared vaults, cross-device sync, autofill, and two-factor authentication support. --- # Secure sensitive data with Vault Vault is a password manager in Olares, designed for secure storage and management of sensitive data. With Vault, you can safely store and organize private keys and passwords, digital identities (DIDs) and Olares IDs, one-time passwords (OTPs), and other confidential data. Key features of Vault include: * End-to-end encryption for maximum security * Private and shared vaults for personal and organizational use * Seamless synchronization across devices * Autofill functionality for easy credential input * Strong password suggestions for enhanced account security * Two-factor authentication (2FA) support with OTP management ## Clients Vault's server component runs on Olares, synchronizing data across multiple client devices of a single user. Data is encrypted with a private key during transmission and storage to ensure security. You can access Vault in Olares, or through LarePass on mobile, desktop, and browser extensions for a consistent user experience across platforms. Visit the [official page](https://olares.com/larepass) for LarePass details and download options. ---

Vault basics

Understand vault items, and learn how to securely store and manage your sensitive data in Vault.

Share vault items

Learn how to manage team vault access, and work with shared vaults.

Set up two-factor authentication codes

Learn how to generate and store 2FA codes for enhanced security.

Use autofill with LarePass

Learn how to set up and use autofill for logins with different LarePass clients.
--- ### Manual Olares Wise Index (`docs/manual/olares/wise/index.md`) --- description: Transform your Olares into a powerful information hub with Wise - featuring AI-driven content curation, cross-platform aggregation, and seamless bookmarking capabilities. --- # Curate information hub with Wise Wise is a local-first, AI-driven modern reader and a core application within the Olares ecosystem. Working together with the LarePass Chrome extension, Wise assists you in collecting, consuming, and managing content from various platforms, thereby creating and maintaining a personal information hub. Key features include: * **Self-hosted recommendation algorithms**: You can run personalized algorithms to filter and sort online content, breaking through the information bubble and receiving diverse and personalized content recommendations. * **Cross-platform content aggregation**: Wise integrates articles, videos, audio, and feeds from different sources, offering you a comprehensive experience. * **Seamless bookmarking**: With the LarePass browser extension, you can save web pages to Olares with a single click, making it easy to access and manage content anytime. ---

Wise basics

Learn the essential tasks for collecting, reading, and managing your content library in Wise.

Discover themed content

Learn how self-hosted recommendation algorithms work in Wise.

Subscribe and manage feeds

Set up and organize your content sources through RSS feeds, manual subscriptions, and the LarePass browser extension.

Add filtered view

Learn how to use advanced filters to organize and display content based on specific criteria like tags, authors, or publication dates.
--- ### Zh Developer Develop Index (`docs/zh/developer/develop/index.md`) # 简介 在 Olares 上开发应用与当下主流的网站开发方法并没有太多区别，只需要额外了解一些 Olares 的基本概念，即可在 Olares 上开发应用。 - [Olares 的核心理念](../../manual/concepts/index.md) - [了解 Olares 应用 Chart 的格式](./package/chart.md) - [Olares 应用 Chart 包的结构](./package/chart.md) - [OlaresManifest.yaml 的配置和字段说明](./package/manifest.md) - [Olares 对 Helm 进行的字段扩展](./package/extension.md) - [探索我们的教程](./tutorial/) - [了解 Olares 的开发工具 Devbox](./tutorial/studio) - [创建首个应用](./tutorial/note/) - [了解一些进阶的技巧](./advanced/) - [提交应用到应用市场](./submit/) --- ### Zh Developer Install Index (`docs/zh/developer/install/index.md`) --- description: Olares 部署的技术详解，包含系统架构、安装流程、环境配置、CLI 功能和版本管理以及更多的 Olares 安装方式。为开发者提供使用 Olares 的核心技术要点。 --- # Olares 安装详解 本章节将为你提供关于 Olares 安装的详细信息和命令参考，帮助你探索、学习并自定义 Olares 的安装。 - [Olares 安装概览](installation-overview.md)：从整体架构和核心组件的角度了解 Olares 的安装过程。 - [Olares 安装流程详解](installation-process.md)：详解 Olares 安装的四个主要安装阶段。 - [Olares Home 介绍](olares-home.md)：了解 Olares 默认安装目录的结构。 - [Olares 环境变量](environment-variables.md)：查找合适的环境变量来自定义安装配置。 - [Olares CLI 参考](./index.md)：使用 Olares CLI 命令行工具，自定义 Olares 安装或进行故障排查。 - [Olares 版本说明](versioning.md)：了解 Olares 的版本号规则、版本类型、分支管理实践以及升级策略。 --- ### Zh Developer Install Installation Overview (`docs/zh/developer/install/installation-overview.md`) --- outline: [2, 3] description: Olares 部署的核心架构，涵盖系统原生层、容器编排曾和容器化层。深入解析 Olares 各层级之间的技术交互。 --- # Olares 安装概述 本文档从宏观的角度介绍了 Olares 的安装流程，重点介绍其整体架构和核心组件，旨在为系统管理员和开发者提供 Olares 运行原理及安装方法的基本了解。 ## Olares 安装的三层结构 Olares 的安装流程分为三个关键层级： - **原生层**：处理 Linux 系统配置与基础环境依赖安装。 - **容器编排层**：部署 Kubernetes 集群，实现服务的自动化管理与扩展。 - **容器化层**：启动容器化的系统核心服务和用户应用，提供最终运行时环境。 安装过程由命令行工具 `olares-cli` 管理。该工具负责协调所有组件的安装、配置以及生命周期管理。 ::: tip 提示 要了解安装的详细过程，请参考 [Olares 安装流程详解](installation-process.md)文档。 ::: ## 原生层 Olares 的安装从原生层开始，确保底层 Linux 环境支持分布式存储、容器运行时和 Kubernetes 集群管理。 该层的配置涵盖核心 Linux 环境设置、文件系统初始化、容器运行时安装以及关键系统服务部署。 ### 环境配置 安装首先配置基本的 Linux 安装环境，如配置域名解析系统（DNS）、安全外壳远程访问协议（SSH）、网络时间协议（NTP）等服务，以确保时间同步与远程管理。 同时，也会安装必要依赖，如 GNU 编译器集合（GCC）、网络工具（net-tools）等系统工具，确保运行时环境。 ### 文件系统配置 文件系统（rootfs）用于存取系统核心组件与用户数据。根据部署需求，Olares 支持以下两种文件系统： - **LocalFS**（默认）：使用本地 Linux 磁盘进行存储，适用于无需网络共享且需要高数据吞吐量的单节点部署。 - **JuiceFS**：为多节点集群提供分布式文件系统。文件数据可以存储在本地安装的 MinIO 实例中，也可以存储在 Amazon S3 这一类远程存储桶中。该配置支持不同存储节点共享统一的存储视图。 :::tip 启用 JuiceFS JuiceFS 和 MinIO 默认不会安装。如需启用，需在安装前设置必要的[环境变量](environment-variables.md#juicefs)或用 [olares-cli 命令](./cli-1.12/prepare#选项)配合 JuiceFS 相应参数安装。 ::: ### 容器运行时：containerd Olares 使用轻量级容器运行时 containerd 进行容器化部署，其主要功能包括： - **容器镜像管理**： - 从内容分发网络（CDN）下载已打包的容器镜像 - 在“准备”阶段将下载的镜像导入至 containerd - 在“安装”环阶段以容器进程的方式启动镜像 - **容器生命周期管理**：启动、停止、重启和监控容器化应用服务。 ::: tip 兼容性问题 如果你的机器之前安装过 containerd（比如通过 Docker 安装），可能会与 Olares 安装的 containerd 有兼容性问题。请在安装 Olares 前卸载现有的 containerd。 ::: ### 系统守护进程：olaresd olaresd 是系统守护进程，在后台运行，提供以下关键管理功能： - **自动配置更新**：当系统发生变化（如 IP 地址变更）时，自动检测并调整相关配置项。 - **远程系统管理**：根据来自 LarePass 客户端或 `olares-cli` 的命令执行远程系统操作，例如 Olares 安装和激活。 ### CUDA 支持 为了让本地 AI 模型和应用启用 GPU 加速，Olares 支持通过 [`olares-cli`](./cli-1.11/gpu.md) 自动检测并安装 CUDA 工具包和相关驱动程序。 ## 容器编排层 容器编排层通过 Kubernetes 将系统组件集成到高效的运行时环境中。 ### Kubernetes 的角色 Kubernetes 是容器编排层的核心，负责实现多组件服务的自动部署、运行、扩展和管理。 与 Docker Compose 或 Docker Swarm 等工具相比，Kubernetes 具有以下优势： - 高可扩展性和生产级可靠性：适用于大规模集群部署和关键任务环境。 - 丰富的社区支持：拥有活跃的社区和丰富的生态系统，可通过 Helm Charts、Operators 和自定义资源定义（CRDs）集成各种应用程序。 ### Olares 支持的 Kubernetes 版本 Olares 支持以下 Kubernetes 部署方式： - **K3s**（默认）：轻量级 Kubernetes 发行版，可优化本地硬件上的资源利用效率。 - **Kubernetes**：完整功能的 Kubernetes 发行版，适用于高级或自定义部署需求。 - **minikube**（仅限 macOS）：设置单节点 Kubernetes 集群的工具，确保一致的功能和用户体验。 ## 容器化层 在容器化层，Olares 各组件和应用协同工作提供系统完整功能。所有 Olares 组件和用户应用都在容器中运行，整个生命周期由 Kubernetes 管理。这确保了系统的高效性、稳定性和可扩展性。 在安装并激活 Olares 后，你就可以通过**控制面板**应用的图形界面查看正在运行的容器。 {width=90%} ## 了解更多 - [Olares 安装流程详解](installation-process.md) - [Olares Home 概述](olares-home.md) - [`olares-cli` 命令行参考](../install/cli-1.11/olares-cli.md) - [Olares 环境变量](environment-variables.md) --- ### Zh Manual Best Practices Index (`docs/zh/manual/best-practices/index.md`) --- description: 通过最佳实践与进阶指南，深入挖掘 Olares 的性能、安全与高级定制能力。. --- # 进阶篇：Olares 最佳实践与高级教程 本节提供深入的操作指南与经验证的最佳实践，帮助你在 Olares 上获得更高性能、更强安全性及更灵活的高级定制。无论是优化环境、保护数据，还是满足高阶工作流需求，这些资源都可作为初始部署之外的实战参考。 - [为 Olares 配置自定义域名](set-custom-domain.md) - [安装多节点 Olares 集群](install-olares-multi-node.md) - [使用 Wise 构建知识中心](organize-content.md) - [设置 SMTP](set-up-SMTP-service.md) --- ### Zh Manual Concepts Index (`docs/zh/manual/concepts/index.md`) --- description: Olares 系统核心概念说明文档，阐述架构设计、身份验证、应用管理、网络配置和数据安全等基础理论。适合开发者理解系统运作机制。 --- # 概述 本章节帮助你了解 Olares 系统，加深对 Olares 工作原理的理解。在以下场景中可以参考本章节： - 开发 Olares 应用 - 管理系统部署 - 排查故障问题 - 优化系统性能 通过以下概念来理解 Olares： - [架构](architecture.md) - [Olares ID](./olares-id.md) - [账户](./account.md) - [应用](./application.md) - [网络](./network.md) - [数据](./data.md) - [密钥](./secrets.md) --- ### Zh Manual Get Started Index (`docs/zh/manual/get-started/index.md`) --- description: Olares 的上手指南，选择适合个人或团队的使用路径。 --- # 快速上手 嗨！欢迎来到 Olares 的世界！让我们帮你在你喜欢的平台上轻松上手 Olares。 ::: tip 想直接体验云端版本？不用自己搭建？来看看 [Olares Space 的介绍](../../space/)吧！ :::

刚认识 Olares？

从创建 Olares ID 开始，轻松搞定初始设置。

→

已是 Olares 用户？

查看完整指南，玩转 Olares 的每一个功能。

→

想用 Olares 开启高效工作？

探索用例和教程，了解 Olares 如何简化你的工作流程并开启新的可能性。

→
--- ### Zh Manual Larepass Index (`docs/zh/manual/larepass/index.md`) --- outline: [2, 3] description: LarePass 用户文档。了解 LarePass 的核心功能与使用方法，包括账户管理、文件同步、设备与网络管理、密码管理，内容收藏等，并提供下载与安装指南。 --- # LarePass 使用文档 **LarePass** 是 Olares 的官方跨平台客户端，为用户与 Olares 系统之间建立安全桥梁。无论是移动端、桌面端还是浏览器，你都可以随时随地借助 LarePass 实现无缝访问、身份、密码管理、文件同步、内容管理。 ## 主要功能 ### 账户与身份管理 创建和管理 Olares ID，安全备份凭证并连接外部服务。 - [创建 Olares ID](create-account.md) - [备份助记词](back-up-mnemonics.md) - [设置或重置本地密码](back-up-mnemonics.md#设置本地密码) - [管理集成服务](integrations.md) ### 启用专用网络 随时随地通过 LarePass 专用网络访问 Olares。 - [打开专用网络](private-network.md#在-larepass-中启用专用网络) - [排查连接问题](private-network.md#故障排查) ### 设备管理 激活并管理 Olares 设备，通过 LarePass VPN 安全连接。 - [激活 Olares 设备](activate-olares.md) - [双因素登录 Olares](activate-olares.md#使用-larepass-进行双因素验证) - [管理 Olares](manage-olares.md) - [切换有线/无线网络](manage-olares.md#有线切换至无线) ### 安全文件访问与同步 跨设备访问并同步 Olares 文件。 - [使用 LarePass 管理文件](manage-files.md) - [同步与共享文件](sync-share.md) ### 密码与密钥管理 使用 Vault 自动填充凭证、存储密码并生成 2FA 代码。 - [自动填充密码](autofill.md) - [生成 2FA 代码](two-factor-verification.md) ### 知识收藏 通过 LarePass 收集网页内容并订阅 RSS。 - [通过 LarePass 扩展收集内容](manage-knowledge.md#通过-larepass-扩展收集内容) - [订阅 RSS 源](manage-knowledge.md#订阅-rss-源) --- ## 下载与安装 LarePass 前往 [LarePass 官网](https://www.olares.cn/larepass) 获取适用于你设备的最新版本。 ### 安装 LarePass 浏览器扩展 ::: tip 快速访问 安装完成后，可在 Chrome 扩展菜单中固定 LarePass，方便一键启动。 ::: --- ### Zh Manual Olares Index (`docs/zh/manual/olares/index.md`) --- description: 通过 Olares 系统应用文档了解如何使用 Olares，包括个性化设置、应用管理、文件处理、安全配置和团队协作功能。 --- # Olares 系统应用文档 Olares 系统应用是 Olares 生态的核心组成部分，它们预装在你的 Olares 系统中，旨在提供一套基础且强大的工具集，帮助你高效地管理文件、应用、设置系统，管理知识、以及完成更多日常任务。理解这些系统应用的功能和价值，将使你能够充分利用 Olares 的潜力，打造一个符合你个人需求的工作和生活环境。 本文档将帮助你全面掌握 Olares 系统应用的使用方法，打造一个符合个人工作和生活需求的个人云环境。 ## 系统应用能做什么？ 探索以下指南，充分发挥 Olares 内置应用的价值： - **[导航并自定义桌面](./desktop.md)**：启动应用、整理工作区并在 Olares 中全局搜索。 - **[安装和管理应用](./market.md)**：在开放、无许可的应用商店中发现、安装、更新或移除应用及推荐算法。 - **[存储、同步与访问文件](./files/)**：在集中式存储中安全上传、下载、组织与共享文件，并实现实时同步。 - **[使用 Vault 管理密码](./vault/)**：安全存储凭据、管理数字身份并生成一次性验证码。 - **[使用 Wise 收集与整理知识](./wise/)**：从多平台收集、消费并管理内容，获取个性化推荐，构建个人信息中心。 - **[使用设置配置系统](./settings/)**：在单一界面完成用户、应用、网络、集成、安全、外观、备份等设置。 - **[通过控制面板监控、管理应用](./controlhub/)**：在单一控制台监控系统状态、管理应用服务并优化 Olares 环境。 - **[通过仪表盘了解系统状态](./resources-usage.md)**：以直观界面查看实时资源使用和性能指标。 - **[设计专属 Olares 个人主页](profile.md)**：定制个人主页，展示身份并与他人分享。 --- ### Developer Contribute Olares Id Verifiable Credential Overview (`docs/developer/contribute/olares-id/verifiable-credential/overview.md`) # VC Service The purpose of this documentation is to help you understand how to configure various schemas and create Issuers and Verifiers for your own scenarios using: - [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) and [did-gate](https://github.com/Above-Os/did-gate) by Terminus. - [SSI Service](https://github.com/TBD54566975/ssi-service) by the tbd team. ::: tip If you want to engage in lower-level development, read the [protocol standard](#reference) together with the source code in [SSI SDK](https://github.com/TBD54566975/ssi-sdk). ::: ## Introduction We have learned about [VC](/manual/concepts/vc.md) and the basic process for applying VCs. Before we get into the implementation details, we can familiarize ourselves with the terms that we will encounter in the real communication process of Wallet, Verifier and Issuer. | Term | Definition | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Holder | Holders are entities that have one or more verifiable credentials in their possession. Holders are also the entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. | | Issuer | A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. | | Verifier | Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. | | Verifiable Credential | Is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build Verifiable Presentations, which can also be cryptographically verified. The claims in a credential can be about different subjects. PEX accepts Verifiable credential in 3 forms: 1. JSON_LD which is known in our system as IVerifiableCredential, 2. JWT-Wrapped VC which is known in our system as JwtWrappedVerifiableCredential or string which is a valid Verifiable credential jwt | | Verifiable Presentation | s a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. | | Manifest | Credential Manifests are used to describe which credentials are available for issuance. | | Application | The format provided by Holder to Issuer, including | | Presentation Definition | Presentation Definitions are objects that articulate what proofs a Verifier requires. | | Presentation | Data derived from one or more verifiable credentials, issued by one or more issuers | | Submission | TBC | | Definition | TBC | | Schema | All different Manifest, Application, Credential, Presentation, Definition need to define Schema with JSON. The service will verify the correctness of submitted data and then go into business process. | ## Reference The following reference materials come from the [SSI SDK](https://github.com/TBD54566975/ssi-sdk) project. ### Specifications Here are a set of references to specifications that this library currently supports. It is a dynamic set that will change as the library evolves. - [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C Proposed Recommendation 03 August 2021 - [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) W3C Recommendation 09 November 2021 - Supports [Linked Data Proof](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) formats. - Supports [VC-JWT and VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) formats. - [Verifiable Credentials JSON Schema Specification](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Draft Community Group Report, 21 September 2021 - [Presentation Exchange 2.0.0](https://identity.foundation/presentation-exchange/) Working Group Draft, March 2022 - [Wallet Rendering Strawman](https://identity.foundation/wallet-rendering/), June 2022 - [Credential Manifest](https://identity.foundation/credential-manifest/) Strawman, June 2022 - [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) Draft Community Group Report 04 April 2022 ### Signing Methods > - [Data Integrity 1.0](https://w3c.github.io/vc-data-integrity/) Draft Community Group Report > - [Linked Data Cryptographic Suite Registry](https://w3c-ccg.github.io/ld-cryptosuite-registry/) Draft Community Group Report 29 December 2020 > - [JSON Web Signature 2020](https://w3c-ccg.github.io/lds-jws2020/) Draft Community Group Report 09 February 2022 > - [VC Proof Formats Test Suite, VC Data Model with JSON Web Signatures](https://identity.foundation/JWS-Test-Suite/) Unofficial Draft 09 March 2022 This implementation's compliance with the JWS Test Suite can be found here. > - Supports both JWT and Linked Data proof formats with [JOSE compliance](https://jose.readthedocs.io/en/latest/). --- ### Developer Develop Tutorial Note Index (`docs/developer/develop/tutorial/note/index.md`) # Create Your First Olares App You can learn how to develop an Olares app using DevBox through this tutorial. The tutorial shows how to make a simple [Note](https://github.com/beclab/olares-app-demo) tool. It demonstrates how to start from scratch and develop a complete Olares App. The tutorial includes three parts: 1. [Create an App](./create.md)
This section provides a step-by-step guide on how to create an Olares App and set up the initial development environment. 2. [Backend Development](./backend.md)
In this section, you'll learn how to use DevBox's IDE to develop the backend programs in `Golang` and provide API interfaces for the frontend. 3. [Frontend Development](./frontend.md)
In this section, you'll learn how to use DevBox's IDE to develop frontend pages, using `NodeJS` as an example. --- ### Zh Developer Contribute System App Overview (`docs/zh/developer/contribute/system-app/overview.md`) # 开发 Olares 的系统应用 ::: tip 前置知识： - 用 DevBox 调试第三方应用 - 用 DevBox 开发程序 - 了解 Olares 的架构和机制 ::: 经过一年半开发，Olares 团队在开发系统应用时已经逐渐迁移到 DevBox 上。 下面我们将演示如何在 Devbox 里调试 Desktop 的前端代码。 1. 在 DevBox 中创建应用 2. 配置 [deployment.yaml](./deployment) 3. 配置 [OlaresManifest.yaml](./olares-manifest) 4. 安装应用 5. 配置 [nginx.conf](./install) 还有[其它](./other)一些开发注意事项。 --- ### Zh Developer Develop Advanced Index (`docs/zh/developer/develop/advanced/index.md`) # Advanced 1. [Terminus Info](./terminus-info) 2. [Service Provider](./provider.md) 3. [AI](./ai.md) 4. [Cookie](./cookie.md) 5. [数据库](./database.md) 6. [账户](./account.md) 7. [应用市场](./market.md) 8. [Websocket](./websocket.md) 9. [文件上传](./file-upload.md) 10. [密钥](./secret.md) 11. [Kubesphere](./kubesphere.md) --- ### Zh Developer Develop Submit Index (`docs/zh/developer/develop/submit/index.md`) --- outline: [2, 3] --- # 提交应用 ## 详细步骤 **基本流程** 1. 在 Olares 上测试你的应用，根据[指南](../package/chart.md)创建 Olares 应用 Chart。 2. Fork 官方 [Olares 应用市场仓库](https://github.com/beclab/apps)。添加应用 Chart。创建 PR 到 `beclab/apps:main`。 3. 等待 **GitBot** 检查你的 PR。如果需要，修改 PR 直至通过。 4. PR 合并后，你的应用程序就可以启动了。 ### 1. 创建并测试 Olares 应用 在提交应用程序之前，请确保它已在你的 Olares 上经过完整测试。 - 使用 DevBox 的开发容器在真实的在线环境中测试和调试你的应用。 [了解有关 DevBox 的更多信息](../tutorial/studio)。 - 使用 Market 应用程序中的[自定义安装](../../../manual/olares/market#install-custom-applications) 进行用户测试。 ### 2. 提交应用 应用提交需要通过 **Pull Request** 完成。具体步骤如下： - 从官方 [Olares 应用市场仓库](https://github.com/beclab/apps)创建 fork，并在你的 fork 仓库中添加应用 Chart。 - 创建一个指向 `beclab/apps:main` 分支的 Draft PR。 - 请按照模板要求编辑 PR 标题和内容。 - **PR 标题**必须符合以下格式：[PR 类型][文件夹名][版本]标题内容 - `PR 类型`包括： - NEW: 提交新应用 - UPDATE: 更新已成功合并的应用 - REMOVE: 移除已成功合并的应用 - SUSPEND: 暂停已成功合并的应用在应用商店的分发 - `文件夹名`是你的 Olares 应用 Chart 名称。必须符合 [chart 规范](../package/chart.md)中的命名要求。 - `版本`指你的应用 chart 的` Chart 版本`，需要与 `Chart.yaml` 中的 `version` 字段和 `OlaresManifest.yaml` 元数据部分保持一致。 - 为防止你的 PR 被错误解析或关闭，请遵守以下规则： - PR 标题只能包含一个 `PR 类型`、`文件夹名`和`版本`。 - 你的 `PR 类型`必须是预定义类型之一。 - PR 只能添加或修改PR标题中声明的`文件夹名`下的内容。 - 同一`文件夹名`同时只能存在一个 Open PR 或 Draft PR。 - 你必须是要修改的文件夹的所有者之一。所有者列在chart中的`owners`文件中。如果你正在提交新应用，你的 GitHub 用户名应该包含在 `owners` 文件中。 - 在 Draft PR阶段，你可以持续调整 PR 内容并添加新的提交。一切就绪后，点击 **Ready for review** 按钮提交 PR 并调用 **GitBot** 进行检查。 :::info 注意 PR 的标题和内容对于 **GitBot** 来说至关重要。请按照模板规范填写。**GitBot** 可能会自动关闭任何无效的PR。 ::: ### 3. 跟踪 PR 状态 - 当你的 PR 被标记为 `PR 类型`时，表示你的 PR 标题有效。请**不要在之后修改 `PR 类型`。**如果它不符合你的意图，只需关闭它并创建一个新的。 - 你可以通过状态标签跟踪PR的进度： - `waiting to submit`: 你的 PR 存在问题，需要在合并前进行进一步修改。 - `closed`: 你的 PR 无效或包含无法纠正的错误。 - `waiting to merge`: 一切进展顺利。你的PR已通过检查，现在正等待 **GitBot** 自动合并。 - `merged`: 你的PR已被自动合并到`beclab/apps:main`中。 - 如果 **GitBot** 自动关闭了你的 PR，请**不要重新打开**它。这表示 PR 存在不可修复的问题，**GitBot** 不得不终止检查流程。你可以在进行必要修改后提交新的 PR。 - 当 PR 处于 `waiting to submit` 状态时，你可以继续提交 Commits 来修改你的 PR。提交 Commit 后，GitBot将重新检查你提交的应用 chart 文件并更新 PR 状态。 - 一旦你的 PR 通过所有检查，它将自动合并到 `beclab/apps:main` 中。应用将在一段时间后在**Olares Market**上列出。 - 如果你在提交过程中遇到任何问题，随时可以联系 Olares 团队或寻求社区帮助。 ## 管理你的应用 你可以通过创建 Pull Request 到 `beclab/apps:main` 继续管理和维护你的应用。你可以升级应用、修改其可用性，或从**Olares Market**完全移除它。 管理应用的流程与提交类似。你创建特定类型的 Pull Request，GitBot 会处理剩余工作。Olares 使用应用 chart 根目录中的**特殊控制文件**来管理应用状态。这些**特殊控制文件**是带有特定后缀的空文件，如 `.suspend` 和 `.remove`。 :::info 注意 初次提交时不应包含 ".suspend" 或 ".remove" 文件。 ::: ### 更新 当你需要更新已发布的应用时，你需要创建一个 `UPDATE` PR。 **请注意：** - 每当你对应用chart进行更改时，如升级程序、更新元数据或更改所有者列表，请务必升级你的chart版本。 - 更新后的应用chart版本必须***大于***仓库中的当前版本。 - 更新的应用chart根目录中不包含 `.suspend` 或 `.remove` 文件。 - **Olares 应用市场**不提供版本回滚。如果你的应用存在任何问题，你需要提交新版本来修复它。 - 为避免潜在冲突，我们建议同步你的fork并将PR的提交变基到最新的main分支。 ### 暂停 如果出于任何原因你想暂时禁用你的应用在**Olares 应用市场**的下载和安装，请提交一个`SUSPEND` PR。 **请注意：** - 提交的应用chart版本必须与仓库中的当前版本***匹配***。 - 你提交的根目录应包含 `.suspend` 文件，且不应包含 `.remove` 文件。 - 一旦暂停PR通过检查并合并，应用商店将停止列出你的应用。 - 已经下载并安装应用的用户在暂停后可以继续使用它。 ### 移除 如果出于任何原因你想从**Olares Market**移除你的应用，请提交一个 `REMOVE` PR。 **请注意：** - 完全清空当前应用目录中的文件，并在根目录中添加一个 `.remove` 文件。 - 一旦移除PR通过检查并合并，应用商店将移除你的应用。 - 你将无法在未来重用相同的目录或应用chart名称。 - 已经下载并安装应用的用户在移除后可以继续使用它。 ## 推广你的应用 通过使用组织良好的应用描述、截图和宣传图片来突出显示应用的特点和功能，可以帮助吸引Market中的新用户。截图和预览可以直观地展示用户体验，帮助你的应用脱颖而出。 要在应用详情页添加宣传图片，请在 `OlaresManifest.yaml` 文件的 `spec` 部分的 `promoteImage` 字段中包含这些资源的链接。 :::info **Olares 应用市场的资源规范** - 应用的**图标**必须为 PNG 或 WEBP 格式，大小不超过 512 KB，尺寸为 256x256 像素。 - 强烈建议至少上传 2 张**截图**用于推广。**截图**必须为 JPEG、PNG 或 WEBP 格式，每张大小不超过 8MB，尺寸为1440x900像素。你最多可以上传 8 张**截图**。 - 如果你希望你的应用在市场中被推荐，则需要一张**特色图片**。在 `OlaresManifest.yaml` 文件的 `spec` 部分的 `featuredImage` 字段中添加此图片的链接。图片必须为 JPEG、PNG 或 WEBP 格式，大小不超过 8MB，尺寸为 1440x900 像素。 ::: ## 邀请他人协作 有两种方式可以邀请他人一起开发Olares应用： 1. 将其他开发者的 GitHub 用户名添加到 `owners` 文件中。列在`owners`中的每个开发者都可以独立 fork 仓库并提交他们的更改。 2. 将其他人添加为你 fork 仓库的协作者。在这种情况下，你作为代表创建 Pull Request，所有其他人可以共同提交到计划合并的分支。 --- ### Zh Developer Develop Tutorial Index (`docs/zh/developer/develop/tutorial/index.md`) # 教程 欢迎阅读 Olares 应用开发指南。这些详细的教程将逐步指导你从零开始构建 Olares 应用。 在开始前，你可以先了解一些 Olares 的基本概念，如： - [Olares 的组成](../../../manual/concepts/architecture.md) - [Olares 应用 Chart](../../develop/package/chart.md) - [Olares 在 Helm 上的扩展](../package/extension.md)。 这些基础知识将帮助你更有效地掌握的开发流程。 你还可以先了解下 [DevBox](studio.md)，这是 Olares 为开发人员构建 Olares 应用程序提供的内置应用程序。 如果你是 Olares 开发的新手，想直接开始编码，可以从[创建首个应用](./note/index.md)开始。本教程将指导你构建一个小型笔记应用程序。 --- ### Zh Manual Olares Controlhub Index (`docs/zh/manual/olares/controlhub/index.md`) --- outline: [2, 3] description: 熟悉 Olares 中控制面板应用的操作界面，了解如何导航资源视图、管理工作负载和服务等。 --- # 通过控制面板管理 Olares **控制面板**是 Olares 的控制台，为开发者和用户提供对系统操作和底层环境的精准控制。本文档将帮助你了解控制面板的界面并高效监控资源。 ## 导航 ### Olares 通过以下三种视图监控应用的状态： - **浏览**（以应用为中心）：通过三列布局导航与特定应用相关的资源使用情况，高效定位资源。 - **命名空间**（以用户为中心）：访问每位用户的应用资源使用情况的详细信息，并支持排序和筛选。 - **容器组**：以最细粒度监控容器（Pod）的状态和资源消耗。 ### 资源 查看和管理 Kubernetes 系统资源： - **网络**：监控系统中实施的网络安全策略以及每个命名空间的网络连接性。 - **CRDs**：管理系统中的各种自定义资源声明。 ### 中间件 查看 Olares 中各种中间件服务的使用情况。 --- ### Zh Manual Olares Files Index (`docs/zh/manual/olares/files/index.md`) --- description: 使用 Olares 文件管理器进行文件存储、同步和访问，实现高效的文件管理和团队协作。 --- # 管理文件 Olares 内置的文件应用为用户提供了安全高效的文件存储与同步解决方案，支持从任何设备或浏览器访问各种文件类型。主要优势包括： * **随时随地访问**：使用任意设备端的浏览器，从任何位置查看、下载或共享存储在 Olares 中的文件。 * **无缝同步**：确保数据在所有设备间保持最新。 * **集中存储**：简化信息检索与集成，无论是个人文档还是团队共享资料，均可轻松访问、管理与更新。 ## 界面概览 文件管理器的界面类似于 Windows 资源管理器或 macOS 的访达，允许你整理和访问文档、图片、视频或其他文件。主要由以下三个部分组成： * **存储盘**（Drive）：用于存储不需要频繁同步或修改的文件。 * **同步盘**（Sync）：用于在设备间同步文件和目录。 * **应用盘**（Application）：存储应用与缓存数据，仅用于开发和调试目的。 * **云存储** （Cloud Drive）：用于加载、访问第三方云存储服务包括 Google Drive、Drop Box、 AWS S3、腾讯云对象存储服务（COS）。 ---

添加、编辑和下载文件

了解 Olares 中文件管理的基本操作。

同步和共享文件

了解如何在设备间保持文件更新，以及如何与其他 Olares 成员共享文件。

挂载 SMB

了解如何在 Olares 中挂载并访问 NAS 设备或网络服务器上的 SMB 共享文件夹。

挂载云存储

了解如何在 Olares 中挂载并访问第三方云存储服务。
--- ### Zh Manual Olares Settings Index (`docs/zh/manual/olares/settings/index.md`) --- description: 使用设置应用管理和配置你的 Olares，包括个性化体验、安全设置、服务集成等功能。 --- # 设置和管理 Olares Olares 的**设置**提供了简洁直观的界面，让你轻松配置并管理 Olares。这里是个性化设置、系统安全、服务集成、应用管理等操作的中心入口。 设置包含以下功能模块： - **安全管理**：管理登录设备和系统安全设置。 - **账户管理**：创建并管理 Olares 集群中的用户。 - **应用管理**：监控并配置各个应用的运行状态与行为。 - **服务集成**：为 Olares 连接外部服务与工具。 - **外观设置**：设置系统语言与背景等外观选项。 - **网络配置**：配置 FRP、VPN，并编辑 hosts 文件。 - **备份与恢复**：创建并管理指定目录的备份与恢复任务。 - **系统更新**：查看系统详情并执行版本更新。 - **日志导出**：生成并导出系统日志，用于诊断问题。 --- ### Zh Manual Olares Vault Index (`docs/zh/manual/olares/vault/index.md`) --- description: 使用 Vault 安全存储和管理敏感数据。了解端到端加密功能和跨设备同步，轻松管理密码、数字身份和一次性密码。 --- # 密钥管理 Vault 是 Olares 中的密码管理器，旨在安全存储和管理敏感数据。通过 Vault，你可以安全地存储和组织私钥与密码、数字身份 (DIDs) 、Olares ID、一次性密码 (OTPs) 以及其他机密数据。 Vault 的关键功能包括： * 端到端加密，确保最高安全性 * 私有和共享 Vault，满足个人与组织需求 * 跨设备的无缝同步 * 自动填充功能，轻松输入凭据 * 支持 2FA（双因素认证），管理 OTP ## 客户端 Vault 的服务器组件运行在 Olares 上，同步单个用户的多个客户端设备。数据在传输和存储过程中使用私钥加密，确保安全性。 你可以通过 Olares 使用 Vault，也可以通过移动设备、桌面和浏览器扩展的 LarePass 客户端访问，实现跨平台一致的用户体验。 访问 [LarePass 页面](https://olares.cn/larepass) 获取 LarePass 的详细信息和下载选项。 ---

Vault 基本操作

了解 Vault 项目及基本操作，学习如何在 Vault 中安全存储和管理敏感数据。

共享 Vault 项目

学习如何管理团队 Vault 访问权限，以及使用共享 Vault。

设置双因素认证代码

学习如何生成并存储 2FA 代码以增强安全性。

使用 LarePass 的自动填充功能

学习如何设置和使用自动填充功能，适配不同的 LarePass 客户端。
--- ### Zh Manual Olares Wise Index (`docs/zh/manual/olares/wise/index.md`) --- description: 使用 Wise 智能内容聚合平台，利用本地优先和 AI 驱动功能，在 Olares 中创建个性化信息中心，实现跨平台内容的智能管理与推荐。 --- # 使用 Wise 一站式聚合、管理内容 Wise 是一款以本地优先和 AI 驱动的现代阅读器，是 Olares 生态系统中的核心应用之一。它帮助你从各种平台收集、阅读和管理信息，从而创建并维护个人信息中心。 关键功能包括： * **自托管推荐算法**：你可以运行个性化算法过滤和排序在线内容，打破信息茧房，接收多样化和个性化的内容推荐。 * **跨平台内容聚合**：Wise 集成文章、视频、音频及其他多媒体内容，为你提供全面的阅读体验。 * **无缝书签功能**：通过 LarePass 浏览器扩展，你可以一键将网页保存到 Olares，随时访问和管理内容。 ---

Wise 基础知识

了解 Wise 中收集、阅读和管理内容库的基本操作。

发现主题内容

了解 Wise 中的自托管推荐算法如何工作。

订阅和管理订阅源

通过 RSS 订阅、手动订阅和 LarePass 浏览器扩展设置并组织你的内容来源。

添加过滤视图

了解如何使用过滤视图，根据标签、作者或发布日期等条件来整理和显示内容。
--- ### Zh Developer Contribute Olares Id Verifiable Credential Overview (`docs/zh/developer/contribute/olares-id/verifiable-credential/overview.md`) # VC 服务 本文档旨在帮助你了解如何使用以下工具，为你自己的场景配置各种 schema 并创建发行方 (Issuers) 和验证方 (Verifiers)： - Olares 的 [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) 和 [did-gate](https://github.com/Above-Os/did-gate) - tbd 团队的 [SSI Service](https://github.com/TBD54566975/ssi-service) ::: tip 如果你想进行更底层的开发，请结合 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 中的源代码阅读[协议标准](#reference)。 ::: ## 简介 我们已经了解了 [VC](/zh/manual/concepts/vc.md) 的概念以及申请 VC 的基本流程。 在深入实现细节之前，我们可以先熟悉一下在钱包 (Wallet)、验证方 (Verifier) 和发行方 (Issuer) 的实际通信过程中会遇到的术语。 | 术语 | 定义 | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **持有方 (Holder)** | 持有一个或多个可验证凭证的实体。持有方也是向验证方提交证明以满足其在“呈现定义 (Presentation Definition)”中描述的需求的实体。 | | **发行方 (Issuer)** | 一个实体可以扮演的角色，通过对一个或多个主体断言声明，从这些声明中创建可验证凭证，并将其传输给持有方。 | | **验证方 (Verifier)** | 定义了需要从持有方那里获取何种证明（通过“呈现定义”）以进行交互的实体。 | | **可验证凭证 (VC)** | 一种防篡改的凭证，其所有权可以被加密验证。可验证凭证可用于构建可验证表述 (Verifiable Presentations)，该表述也可被加密验证。凭证中的声明可以关于不同的主体。PEX 接受三种形式的可验证凭证：1. JSON_LD，在我们的系统中称为 IVerifiableCredential；2. JWT 包装的 VC，在我们的系统中称为 JwtWrappedVerifiableCredential；或 3. 字符串，即一个有效的可验证凭证 jwt。 | | **可验证表述 (VP)** | 一种防篡改的表述，其编码方式使得数据的所有权在经过加密验证后可以被信任。 | | **清单 (Manifest)** | 凭证清单 (Credential Manifests) 用于描述哪些凭证可供发行。 | | **申请 (Application)** | 持有方提供给发行方的格式。 | | **呈现定义 (Presentation Definition)** | 阐明验证方需要何种证明的对象。 | | **呈现 (Presentation)** | 源自一个或多个发行方所发行的一个或多个可验证凭证的数据。 | | **提交 (Submission)** | TBC (待补充) | | **定义 (Definition)** | TBC (待补充) | | **Schema** | 所有不同的清单、申请、凭证、呈现、定义都需要使用 JSON 来定义 Schema。服务将验证所提交数据的正确性，然后进入业务流程。 | ## 参考资料 以下参考资料来自 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 项目。 ### 规范 以下是本库目前支持的一系列规范参考。这是一个动态集合，会随着库的演进而变化。 - [去中心化标识符 (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C 建议提案 2021年8月3日 - [可验证凭证数据模型 v1.1](https://www.w3.org/TR/vc-data-model/) W3C 推荐标准 2021年11月9日 - 支持 [链接数据证明 (Linked Data Proof)](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) 格式。 - 支持 [VC-JWT 和 VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) 格式。 - [可验证凭证 JSON Schema 规范](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) 社区组报告草案 2021年9月21日 - [呈现交换 (Presentation Exchange) 2.0.0](https://identity.foundation/presentation-exchange/) 工作组草案 2022年3月 - [钱包渲染草案 (Wallet Rendering Strawman)](https://identity.foundation/wallet-rendering/) 2022年6月 - [凭证清单 (Credential Manifest)](https://identity.foundation/credential-manifest/) 草案 2022年6月 - [状态列表 (Status List) 2021](https://w3c-ccg.github.io/vc-status-list-2021/) 社区组报告草案 2022年4月4日 ### 签名方法 > - [数据完整性 (Data Integrity) 1.0](https://w3c.github.io/vc-data-integrity/) 社区组报告草案 > - [链接数据加密套件注册表 (Linked Data Cryptographic Suite Registry)](https://w3c-ccg.github.io/ld-cryptosuite-registry/) 社区组报告草案 2020年12月29日 > - [JSON Web 签名 (JSON Web Signature) 2020](https://w3c-ccg.github.io/lds-jws2020/) 社区组报告草案 2022年2月9日 > - [VC 证明格式测试套件，使用 JSON Web 签名的 VC 数据模型](https://identity.foundation/JWS-Test-Suite/) 非官方草案 2022年3月9日 本实现对 JWS 测试套件的合规性可以在此处找到。 > - 支持 JWT 和链接数据证明两种格式，并符合 [JOSE 规范](https://jose.readthedocs.io/en/latest/)。 --- ### Zh Developer Develop Tutorial Note Index (`docs/zh/developer/develop/tutorial/note/index.md`) # 创建你的首个 Olares 应用 你可以通过本教程学习如何使用 DevBox 开发一个 Olares 应用。 整个教程以开发一个简单的 [Note](https://github.com/beclab/terminus-app-demo) 工具为例。展示如何从创建应用开始，开发一个完整的 Olares 应用。 整个教程分为以下3个部分： 1. [创建应用](./create.md)
展示如何创建一个 Olares 应用，并逐步配置这个应用的初始化开发环境。 2. [开发后端](./backend.md)
学习如何利用 DevBox 的 IDE 完成后端 Golang 程序的开发，并为前端提供 API 接口。 3. [开发前端](./frontend.md)
以 NodeJS 为例，学习如何在 DevBox 的提供的 IDE 中开始前端页面的相关开发。 --- ### Manual Docs Home (`docs/manual/docs-home.md`) --- description: Learn about Olares, an open-source sovereign cloud OS for local AI. Discover how to self-host services, run AI applications, manage files, and collaborate securely with enterprise-grade features. --- # Olares documentation ## What is Olares? Olares is an open-source personal cloud operating system designed to empower you to own and manage your digital assets locally. Instead of relying on public cloud services, you can deploy powerful open-source alternatives locally on Olares, such as Ollama for hosting LLMs, SD WebUI for image generation, and Mastodon for building censor free social space. Imagine the power of the cloud, but with you in complete command. With Olares, self-hosting is no longer a daunting task. It simplifies complex processes like network setup, domain management, and service orchestration, enabling both beginners or experienced users to focus on what truly matters. Privacy and independence are at the core of Olares. It is perfect for individuals or teams who want to avoid relying on centralized platforms. Your data stays on your hardware, and all tasks are processed locally, so your sensitive information never leaves your control. Olares gives you complete ownership of your data and infrastructure without sacrificing performance or simplicity.

New to Olares?

Check out the get-started guide to set up Olares on your local machine

→
## Highlighted features Olares offers a wide array of features designed to enhance security, ease of use, and development flexibility: - **Enterprise-grade security**: Secure your self-hosted cloud with simplified network configuration using Tailscale, Headscale, Cloudflare Tunnel, and FRP. - **Secure and permissionless application ecosystem**: Access nearly 100 free applications in a secure, sandboxed environment. [See what Olares Market has to offer](https://market.olares.com/). - **Unified file system and database**: Support automated scaling, backups, and high availability. - **Single sign-on**: Log in once to access all applications within Olares with a shared authentication service. - **AI capabilities**: Manage GPU resources, host AI models locally, and build private knowledge bases with complete privacy. - **Built-in applications**: Get started with essential pre-installed applications such as Files, Vault, Wise, Profile and Dashboard. - **Seamless anywhere access**: Access your devices from anywhere using dedicated clients for mobile, desktop, and browsers. - **Development tools**: Build and port applications easily with comprehensive development tools. ## Key use cases - 🖥️ **Homelab server**: Turn your personal devices into a versatile homelab for experimenting with containerized applications, running local AI models, managing self-hosted services, or testing cloud technologies—all within your own private infrastructure. - 🤖 **Local AI**: Host and run cutting-edge open-source AI models—including large language models, image generation, and speech recognition—directly on your devices. Build custom AI assistants that integrate with your data and applications while keeping everything private and secure. - 💻 **Personal data repository**: Securely store, sync, and manage your photos, documents, and important files in a unified, private storage system accessible from anywhere. - 🛠️ **Self-hosted workspace**: Create a free, collaborative workspace for your team or family with open-source alternatives to commercial productivity tools. - 🎥 **Private media server**: Turn your personal media collection into your own streaming service, hosted entirely on your devices. - 🏡 **Smart home**: Use Olares as the central control point for managing IoT devices and home automation. - 🤝 **Decentralized social media**: Host decentralized social media platforms like Mastodon, Ghost, or WordPress to build your personal brand without the risks of bans or platform fees. ## Pick your path Before you roll up your sleeves and get your hands dirty with Olares, feel free to take a quick tour. Here are some alternative paths to get a feel for what Olares can do.

Explore use cases

Discover real-world applications and see how Olares solves common challenges.

Learn how-tos

Comprehensive system app guides covering daily tasks of using Olares.

Understand Olares

Grasp the fundamental principles and architecture behind Olares.
## Other resources - [Develop Olares apps](../developer/develop/) - [Join our community on Discord](https://discord.com/invite/BzfqrgQPDK) - [Check out Olares blogs](https://blog.olares.com/) --- ### Manual Glossary (`docs/manual/glossary.md`) --- description: Technical glossary of Olares, providing standard definitions and explanations for common technical concepts. Alphabetically organized for easy reference of professional terminology. --- # Glossary
C | D | F | T | V
## C ### CNAME Record A CNAME (Canonical Name) record is a type of DNS (Domain Name System) record that maps your custom domain name to an Olares-provided address, enabling domain-to-application mapping. ## D ### DID A Decentralized Identifier (DID) is a unique digital identification method that enables any person or entity to have a persistent, unique identity on the network. This identifier is fully independent and doesn't require verification or registration through a central authority. A DID is a unique string that starts with "did" and follows specific formatting and naming conventions. ## F ### FRP Fast Reverse Proxy (FRP) is a high-performance reverse proxy application designed for internal network penetration scenarios. It enables servers behind NAT or firewalls to provide services externally, even without public IP addresses. FRP helps users easily expose internal services to the public network. ## T ### TOTP Time-Based One-Time Password (TOTP) is a time-based algorithm for generating one-time passwords, widely used in two-factor authentication (2FA). It generates single-use passwords using a shared key and current time to enhance account security. Each password is valid for a brief period (typically 30 or 60 seconds) before a new one is generated. ## V ### VC Verifiable Credential (VC) is a digital format proof that verifies certain attributes or qualifications of its holder without revealing additional personal information. It involves three primary roles: * Holder: The individual who possesses and uses the credential to prove certain information * Issuer: The authority or entity that creates and issues verifiable credentials * Verifier: The individual or organization that needs to verify the authenticity of the holder's information by validating the credential --- ### Manual Olares Vs Nas (`docs/manual/olares-vs-nas.md`) --- outline: [2, 3] description: Compares Olares and general NAS, highlighting key differences in storage solutions, application ecosystem, virtual machine support, network configuration, and AI capabilities. --- # Compare Olares and NAS Olares is dedicated to creating a one-stop personal cloud experience. Its core functionalities and user positioning are significantly different from traditional Network Attached System (NAS). This document provides a detailed comparison between Olares and general NAS systems. We will highlight key differences in storage solutions, application ecosystem, virtual machine support, network configuration, and AI capabilities, using Unraid and Synology DSM as reference points. ## Overview | Attribute | Olares | NAS | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Introduction | Olares is an open-source
personal cloud operating system. | NAS systems are primarily used for network storage, allowing flexible hardware configurations to manage data and applications. | | Positioning | Focuses on helping users deploy
and manage digital assets locally
as an alternative to public
cloud services.
It supports running powerful
open-source applications locally,
providing users with robust
cloud computing capabilities while
ensuring complete data control
and privacy. | Focuses on individuals and small businesses, solving low-cost data storage reliability issues, but has limitations in application hosting and network security. | | Target users | Regular users without
a technical background | Geek users and small and medium business users | | Transparency | Open-source or source available | Usually closed-source | | Openness | No vendor lock-in | Closed ecosystem | | Application security | Supports application sandboxing,
isolating network, storage,
and computing resources.
Permissions must be declared
and user authorization obtained
during installation. | No application sandboxing. Most third-party applications run with root privileges, and users bear the security risks themselves. | | Network security | Provides public and private
access, using reverse proxy
and VPN to achieve service security. | Only supports external access for limited system applications by default. Custom solutions by users may pose security risks. | | Developer friendliness | Provides development tools
with familiar technology
stacks to deploy services
and develop applications. | Does not support developer tools or application development. | | AI | 1. Advanced GPU management (v1.12)
2. One-click installation support
for over 30 AI applications
and models
3. Supports inter-application and
model calls
4. Supports MCP (v1.12) | ❌ | ## Project information | Attribute | Olares | Unraid | Synology DSM | | ---- | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | Year | 2022 | 2005 | 2000 | | Open Source | ✅ | ❌ | ❌ | | Price | Free | 30-day trial, then requires a one-time paid license | OS sold bundled with hardware | | Positioning | Open-source personal
cloud OS that focuses on
helping users deploy and
manage digital assets locally
as an alternative to public
cloud services. | Network storage OS, allows flexible hardware configurations,
simple and convenient management of data, VMs, and Docker applications | Provides secure and efficient data management systems for businesses of different scales,
helping enterprises control growing data streams | ## Storage features | Feature | Olares | Unraid | Synology DSM | | ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- | | Disk types | System space, user space,
application space, and
application cache are on SSD | System runs on SSD, data stores on HDD |System runs on SSD, data stores on HDD | | Storage pool | ❌ | Supports Parity-protected array similar to JBOD | Supports SHR, Basic, JBOD, RAID 0, RAID 1, RAID 5, RAID 6, RAID 10, and RAID F1 | | LAN file sharing | SMB | SMB, NFS | SMB, NFS, AFP, FTP | | Public file sharing | via Files application | ❌ | via File Station application | | Distributed file system | ✅ | ❌ | ❌ | | Mount external cloud drives | Supports mounting Google
Drive, Dropbox, S3, etc. | ❌ | Supports mounting Google Drive, Dropbox, S3, etc. | | Sync drive | ✅ (Seafile integrated) | ❌ | Synology Drive | | Mount SMB directory | ✅ | ❌ | ❌ | | Mount mobile storage devices | Auto-mount | Manual mount | Auto-mount | | Structured data support | Supports mainstream databases
and data warehouses (e.g., Redis,
PostgreSQL),suitable for production
environments | Can be manually installed,
but not recommended for production environments | Can be manually installed,
but not recommended for production environments | | Local data security | No protection in single-node;
disk data protection via Minio
or Ceph in cluster mode | Allows 1-2 disk failures depending on configuration,
but Parity disk must not fail | Allows 1-2 disk failures depending on RAID configuration | | Remote backup | Supports periodic incremental
encrypted backups via Restic | Flash drive can be manually backed up,
but there is no official backup solution for data drives | Supports multiple official backup solutions | ## Application management | Feature | Olares | Unraid | Synology DSM | | ---------------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------ | | Installation format | Olares package format based
on improved Helm | Dockerfile or Docker Compose | Dockerfile or Docker Compose | | App store | Rich community app ecosystem
with application sandboxing | Rich apps with no sandboxing restrictions. | Fewer apps, extendable via third-party stores | | Application sandbox | ✅ | ❌ | ❌ | | Developer tools | ✅ (Studio) | ❌ | ❌ | | Middleware sharing | Supports mainstream middleware like
PostgreSQL, MongoDB, and Redis | ❌ | ❌ | | Cluster application support | ✅ | ❌ | ❌ | | LDAP integration | ✅ (Requires third-party adaptation) | ❌ | ❌ | | Unified SSO login | ✅ | ❌ | ❌ | | Secret management | ✅ | ❌ | ❌ | ## Virtual machine management | Feature | Olares | Unraid | Synology DSM | | ------------- | --------------------------------------------------------------------- | ------------------------------ | ------------- | | Install via ISO | Not yet supported,
will be supported via Kubevirt | ✅ | ✅ | | Windows | One-click install from
app store, auto-integrates Tailscale,
for secure external RDP access | Install via ISO | Install via ISO | | Steam | Supported in app store,
auto-configures GPU mounting,
streaming, and external access | Requires manual configuration
for GPU passthrough, etc. | ❌ | | Linux | Supported via Dev Containers
in Studio | Install via ISO | Install via ISO | | Android | Supported via redroid | ❌ | ❌ | | Mac | Coming soon | ❌ | ❌ | | Openwrt | Coming soon | ❌ | ❌ | ## Network access | Feature | Olares | Unraid | Synology DSM | | ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Reverse proxy | Integrated Cloudflare
Tunnel and FRP,
supports independent
domain access for
all apps | Only supports access to limited system services | Only supports access to limited system services | | DDNS | No configuration
needed | Manual configuration required.
Supports domain+port access for non-system apps,
but practically cannot provide external services. | Manual configuration required.
Supports domain+port access for non-system apps,
but practically cannot provide external services. | | Custom domain support | ✅ | ❌ | ❌ | | Firewall | Integrated Cloudflare
firewall | ❌ | ❌ | | Free HTTPS certificate | ✅ | ✅ | ✅ | | Two-Factor Authentication Login | ✅ | ✅ | ❌ | | Different security policies for different directories | ✅ | ✅ | ❌ | | Private Access Endpoint | ✅ | ✅ | ❌ | | VPN connection | No configuration needed,
Tailscale integrated | Manual configuration required | Manual configuration required | | VPN-only access mode | ✅ | ❌ | ❌ | ## AI capabilities | Feature | Olares | Unraid | Synology DSM | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ | | GPU management | 1. Supports heterogeneous GPU clusters
across multiple nodes (v1.12)
2. Nvidia GPUs support memory slicing
and time-slicing sharing modes (v1.12) | Supports GPU passthrough on a single node
via manual configuration | ❌ | | Models | 1. Supports mainstream language, image,
video, and voice models, such as Ollama,
VLLM, ComfyUI, SD, Whisper, and ACE-STEP.
2. Supports mainstream open-source AI tools,
such as Dify, Ragflow, MaxKB, and LobeChat. | ❌ | ❌ | | Interoperability | 1. Supports mutual calls between
applications and models
2. System-level support for MCP calls (v1.12) | ❌ | ❌ | --- ### Manual System Architecture (`docs/manual/system-architecture.md`) --- outline: [2, 3] description: Comprehensive guide to Olares architecture covering infrastructure, platform services, and application framework. Learn about container orchestration, storage, networking, and system components. --- # Olares architecture This document provides a comprehensive explanation of the Olares architecture, outlining the purpose and functionality of each layer and its components. ## Infrastructure The infrastructure layer provides essential infrastructure services such as container orchestration, storage, networking, and cluster management. ### Container orchestration Olares supports different Kubernetes distributions depending on the underlying environment: - Linux environments (including WSL, PVE, LXC, Raspberry Pi): Users can choose to install [Kubernetes](https://kubernetes.io/) or the lightweight [K3s](https://k3s.io/), with K3s being the default for its better performance and resource efficiency on local hardware. - macOS: [minikube](https://minikube.sigs.k8s.io/) is used to deploy Kubernetes within a Linux virtual machine, ensuring a unified experience across platforms. Regardless of the chosen Kubernetes distribution, users get consistent core capabilities and experience with Olares. ### Networking The networking stack ensures seamless communication between containers, nodes, and services. Key components include: - [CoreDNS](https://coredns.io/): Provides DNS services for the cluster, ensuring efficient name resolution. - [Calico](https://www.tigera.io/project-calico/): A container networking interface (CNI) that facilitates communication between containers and virtual machines while offering advanced network policy controls. - [Envoy](https://www.envoyproxy.io/): A high-performance, extensible edge and service proxy. Envoy acts as middleware for communication between services, handling load balancing, service discovery, secure communication, and observability. It can operate as a standalone reverse proxy or an API gateway and is often used as a data plane component in service meshes. These components collectively ensure robust, scalable, and secure networking within Olares. ### Distributed storage Olares provides flexibility in storage solutions tailored to both single-node and multi-node setups: - Local storage (default): Ideal for single-node deployments, offering the best read/write performance. - [S3](https://aws.amazon.com/s3/): A cloud-based storage option. Ideal for cloud deployment via S3 or any S3-compatible service. - [MinIO](https://min.io/): A distributed storage solution for self-hosted deployment. Users can either set up a MinIO cluster through Olares or mount an existing one. This approach ensures that applications have access to the necessary storage mechanisms, whether it's for local or distributed environments. ### Distributed key-value storage Olares uses [etcd](https://etcd.io/) as its distributed key-value store. etcd is integral for storing and managing all cluster data for Kubernetes. ### GPU management Olares leverages components like CUDA driver, NVIDIA device plugin, and nvShare, which work in conjunction to manage and provision GPU resources effectively: - CUDA: Acts as the core interface between the GPU hardware and the operating system. - NVIDIA device plugin: Allows GPU resources to be advertised, scheduled, and allocated to containers or pods. - [nvshare](https://github.com/grgalex/nvshare): Allows multiple containers or pods to share a single GPU, enabling both shared and exclusive GPU usage in Olares for better GPU utilization. :::info Currently, Olares GPU support is restricted to deployments with one GPU per node. ::: Starting with Olares v1.11, [CUDA](https://developer.nvidia.com/cuda-toolkit) (12.4 and above) is supported. Changes in the host environment's CUDA configuration can be synchronized with the Olares cluster using `olares-cli`. ### Container management Olares uses [containerd](../developer/install/installation-overview.md#container-runtime-containerd), a lightweight container runtime, for containerized deployments. ### Olares Controller Panel The management of Olares is implemented through the following: - [olares-cli](../developer/install/cli-1.11/olares-cli.md): A command-line tool for managing Olares clusters, applications, and hardware nodes. - [olaresd](../developer/install/installation-overview.md#container-runtime-containerd): A daemon process that monitors hardware and network changes, while also managing cluster upgrades, restarts, and other maintenance operations. These tools streamline installation, maintenance, and scaling for Olares. ## Platform The platform layer services run in containers with middlewares such as databases, messaging system, file system, workflow orchestration, secret management, and observability. ### Relational database Olares uses [PostgreSQL](https://www.postgresql.org/) 16 as its primary relational database. All applications share a single PostgreSQL instance, with each having dedicated accounts for isolation. PostgreSQL also serves as a full-text search engine and vector database. For multi-nodes, [Citus](https://github.com/citusdata/citus) is used, though its production readiness is still under evaluation. In the future, PostgreSQL is expected to migrate to the infrastructure layer for better resource management. ### Key-value cache Olares integrates [KVRocks](https://github.com/apache/incubator-kvrocks), a Redis-compatible persistent key-value store built on RocksDB. KVRocks balances memory and disk storage, making it more resource-efficient than Redis clusters, though slightly slower in performance. ### Message queue Olares integrates [NATS](https://nats.io/), a lightweight and high-performance message-oriented middleware, as the messaging system. NATS ensures low resource consumption while delivering reliable message queues. ### Distributed file system Olares employs [JuiceFS](https://juicefs.com/), a cloud-native distributed file system, to provide POSIX-compatible interfaces for applications. When S3 or MinIO is used as the storage backend, JuiceFS ensures seamless file access across nodes. ### Workflow management Olares uses [Argo Workflows](https://argoproj.github.io/) for workflow orchestration. This Kubernetes-native tool automates complex tasks, such as those required by Olares' distributed recommendation engine. Currently, this functionality is not available to third-party applications. ### Secret management Two secret management solutions are integrated into Olares: - [Vault](https://github.com/beclab/olares/tree/main/apps/vault): Protects sensitive data like accounts, passwords, and mnemonics. It encrypts secrets, ensuring that even if the server is compromised, the data remains secure. Vault is developed by the Olares team based on [Padloc](https://padloc.app/). - [Infisical](https://infisical.com/): A tool for managing sensitive information and preventing secret leaks in Olares development. ### Observability Olares provides observability through the following: - [Prometheus](https://prometheus.io/): Used for system monitoring and resource usage tracking. It collects resource metrics for applications like Dashboard and Market. - [OpenTelemetry](https://opentelemetry.io/)*: Enables tracing of request workflows within the Olares system using eBPF-based monitoring. *(In development)* ### Other middlewares The Olares application store includes common middleware such as [Grafana](https://grafana.com/) for visualization, [MongoDB](https://www.mongodb.com/) for document storage, and [Chaos Mesh](https://chaos-mesh.org/) for chaos testing. ## Application framework The application framework layer provides common functionality and interfaces for system and third-party applications. ### Authentication and authorization Olares uses [LLDAP](https://lldap.example.com/) to manage user accounts and provide LDAP (Lightweight Directory Access Protocol) services for applications. Additionally, [Authelia](https://www.authelia.com/) adds authentication and authorization support, including multi-factor authentication and single sign-on (SSO). ### Application governance Components for application governance include: - [app-service](https://github.com/beclab/app-service): Handles application lifecycle management and resource allocation. - [system-server](https://github.com/beclab/system-server): Manages permissions for inter-application API calls and handles network routing between applications and database middlewares. - image-server: Works with app-service to manage container images required by Olares applications. - [bfl](https://github.com/beclab/bfl): The Backend For Launcher service that aggregates backend interfaces and proxies requests for all system services, including user-isolated system and cluster information. ### Network connectivity Olares supports secure and flexible network connectivity through: - Reverse proxy: Options include [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/), Olares Tunnel, and self-built FRP. - [Tailscale](https://tailscale.com/): Enables users to securely access the system from anywhere. - [Headscale](https://github.com/juanfont/headscale): A self-hosted implementation of the Tailscale control server. ### File service Components for file service include: - File server: Provides essential file management services. - [Seafile](https://www.seafile.com/): An open-source alternative to Dropbox for file synchronization. Olares deeply integrates Seafile, enabling users to synchronize files across multiple devices into a centralized repository. - Drive server: Provides integration with external storage services like Google Drive, Dropbox and S3. - Media server: Streams video files using [ffmpeg](https://github.com/FFmpeg/FFmpeg). ### Knowledge service Components for knowledge service include: - Knowledge: Stores content such as web pages, videos, audio files, PDFs, and EPUBs that users collect via the browser extension or share from their mobile phones using LarePass. This repository is also utilized by the decentralized recommendation engine to store its results. - Download: Uses [aria2](https://aria2.github.io/) and [youtube-dlp](https://github.com/yt-dlp/yt-dlp) to download files, magnet links, and online videos. - Search: Provides full-text search for stored content in Knowledge and Files. - [RSSHub](https://github.com/DIYgod/RSSHub): Generates RSS feeds for easier content subscription. ### AI service Olares empowers AI capabilities with: - Model serving*: Hosts AI models for applications. *(In development)* - RAG interface*: Provides Retrieval-Augmented Generation (RAG) services for files, articles, images, and videos. *(In development)* - Agent & workflow orchestration*: Manages agents and tool workflows. *(In development)* ### System service System services include: - Notification: Delivers system-wide notifications. - Backup*: Supports backups for directories, applications, and clusters. *(In development)* - Upgrade*: Supports automated system upgrades. *(In development)* ## System applications System applications offer tools for managing files, knowledge, passwords, and the system itself. These applications are pre-installed. Users can install additional applications via the Market app. ### Files A file management app that manages and synchronizes files across devices and sources, enabling seamless sharing and access. ### Wise A local-first and AI-native modern reader that helps to collect, read, and manage information from various platforms. Users can run self-hosted recommendation algorithms to filter and sort online content. ### Vault A secure password manager for storing and mangaging sensitive information across devices. ### Market A decentralized and permissionless app store for installing, uninstalling, and updating applications and recommendation algorithms. ### Desktop A hub for managing and interacting with installed applications. File and application searching are also supported. ### Profile An app to customize the user's profile page. ### Settings A system configuration application. ### Dashboard An app for monitoring system resource usage. ### Control Hub The console for Olares, providing precise and autonomous control over the system and its environment. ### DevBox A development tool for building and deploying Olares applications. ## Learn more - To get started with Olares, see the [Getting Started guide](get-started/index.md). - To learn more about the internals of Olares, see the topics in [Concept](concepts/index.md). - For in-depth details about how each component of Olares is orchestrated, see [Olares installation overview](../developer/install/index.md). --- ### Manual What Is Olares (`docs/manual/what-is-olares.md`) # What is Olares Olares is the sovereign cloud that puts you in control. It's an open-source, self-hosted alternative to public clouds like AWS, built to reclaim your data ownership and privacy. By combining the power of Kubernetes with a streamlined interface, Olares enables you to take full control of your data and computing resources. Whether you're managing a homelab, hosting applications, or safeguarding your privacy, Olares delivers the flexibility and capabilities of public clouds, without compromising privacy or security. ## What can you do with Olares Typical use cases of Olares include: - 🖥️ **Homelab server**: Turn your personal devices into a versatile homelab for experimenting with containerized applications, running local AI models, managing self-hosted services, or testing cloud technologies—all within your own private infrastructure. - 🤖 **Local AI**: Host and run cutting-edge open-source AI models—including large language models, image generation, and speech recognition—directly on your devices. Build custom AI assistants that integrate with your data and applications while keeping everything private and secure. - 💻 **Personal data repository**: Securely store, sync, and manage your photos, documents, and important files in a unified, private storage system accessible from anywhere. - 🛠️ **Self-hosted workspace**: Create a free, collaborative workspace for your team or family with open-source alternatives to commercial productivity tools. - 🎥 **Private media server**: Turn your personal media collection into your own streaming service, hosted entirely on your devices. - 🏡 **Smart home**: Use Olares as the central control point for managing IoT devices and home automation. - 🤝 **Decentralized social media**: Host decentralized social media platforms like Mastodon, Ghost, or WordPress to build your personal brand without the risks of bans or platform fees. --- ### Manual Why Olares (`docs/manual/why-olares.md`) --- description: Explore key use cases for Olares including edge AI, personal data management, self-hosted workspace, private media server, smart home control, and decentralized social media deployment. --- # Why Olares Here are some typical use scenarios for Olares. 🤖 **Edge AI**: Run cutting-edge open AI models locally, including large language models, computer vision, and speech recognition. Create private AI services tailored to your data for enhanced functionality and privacy. 📊 **Personal data repository**: Securely store, sync, and manage your important files, photos, and documents across devices and locations. 🚀 **Self-hosted workspace**: Build a free collaborative workspace for your team using secure, open-source SaaS alternatives. 🎥 **Private media server**: Host your own streaming services with your personal media collections. 🏡 Smart home Create a central control point for your IoT devices and home automation. 🤝 Decentralized social media Easily install decentralized social media apps such as Mastodon, Ghost, and WordPress on Olares, allowing you to build a personal brand without the risk of being banned or paying platform commissions. 📚 Learning platform Explore self-hosting, container orchestration, and cloud technologies hands-on. --- ### Space Backup Restore (`docs/space/backup-restore.md`) --- description: Protect your Olares instances with cloud backup and restore features. Handle snapshots, perform restore operations, and manage storage quotas in Olares Space. --- # Back up and restore Olares Space is the official solution to back up snapshots for your Olares instances. You can restore an Olares to its most recent state whenever needed. This section provides instructions for managing backups and restores in Olares Space. :::tip Each Olares is provided with 10 GB of free backup space. Any usage beyond this will be charged according to the cloud provider's pricing. ::: ## View backup list The backup task list shows information for each backup task, including: - Initial creation time - Most recent snapshot time - Overall storage usage Click **View Details** on a task to see its detail page. The detail page shows the storage usage since the task was created and a list of all successful snapshots. :::info NOTE Currently, only restoring from the most recent snapshot is supported. ::: ## Restore backup to the Olares Space Restoring a snapshot to the cloud is similar to setting up a new cloud-based Olares. 1. Set up relevant details. a. Select the cloud service provider and their data center location. b. Choose the hardware configuration for the instance. c. Confirm the snapshot details and enter the backup password. 2. Understand charges for storage and bandwidth.
Each instance includes a certain amount of free storage and traffic. Any usage exceeding these quotas will incur charges. 3. Confirm the order and complete the payment. After that, the Olares begins to install. :::info NOTE During the installation process, Olares will verify the backup password. If it is incorrect, you'll be asked to re-enter the correct one. If you forget the backup password, the restoration process won't be able to continue. In this case, please return your instance and try restoring again. ::: :::info NOTE To avoid conflicts or other unforeseeable problem, you must return the existing Olares that uses the same name before restoring to a cloud-based Olares. ::: --- ### Space Billing (`docs/space/billing.md`) --- description: Understand Olares Space billing system with service charges and payment workflows. Learn about cloud hosting fees, usage based pricing, and promotional credit applications. --- # Billing Olares partners with Stripe for secure payment processing. Your invoices and receipts will be sent via email, allowing you to keep records for analysis. If you have any questions during the payment process, please contact support. ## The scope of billing The following services or products are billed: - **Hosted Olares**: Prepaid product required for setting up an Olares on a cloud provider like AWS or GCS. Pricing varies depends on the provider you choose. - **Host instance traffic**: Postpaid charges for external traffic generated by cloud hosting out of assigned regions. - **Worker instance**: Adding a Worker node to a hosted Olares also incurs monthly charges. Charges will be combined to the monthly bill. - **Cloud storage**: Postpaid product storing system data via JuiceFS. Billed based on usage at the end of the billing cycle. - **Cloud backup/restore**: Backs up host data to public storage. Billed based on usage at the end of the billing cycle. - **Cloudflare tunnel (FRP) traffic**: Postpaid for traffic incurred by self-hosted Olares when services are accessed via public links. - **GPU unit**: Prepaid for GPU-related services. Charges are deducted from prepaid units based on usage. ### Bill generation and payment scenarios The following actions generate bills: - **Creating an Olares in the cloud**: An invoice is generated immediately after you select a cloud provider and configuration. Payment is required for installation to begin. - **Adding/Removing workers**: Bills are generated for adding workers based on the remaining time in the billing period. Similarly, refunds are calculated when removing workers. - **Restoring a snapshot**: Equivalent to creating a new Olares, with monthly charges applied. - **Destroying an Olares**: Fees are settled up to the destruction date. Refunds are processed as applicable. The monthly bill updated once per month. It includes the base subscription fees as well as any additional charges incurred during the month, such as adding a Worker, or extra traffic and storage fees. ## How fees are deducted monthly Olares operates on a monthly billing cycle: - **Automatic deduction**: Your first payment will authorize automatic deductions, with the first payment method set as default. You can disable auto-deductions from the control panel if you prefer to pay manually, but make sure to settle your bills on time to avoid service interruption. - **Payment validity period**: For each purchase, you'll receive a bill valid for 24 hours. ## Use promotional credits or coupons We distribute trial credits or coupons through promotions. - Once you have received trial credits, you can view them in **Billing** > **Balance History**, and apply directly to specific products when you pay. - Once you receive a promotional coupon codes, you can redeem them in **Billing** > **Coupons**. It could be a discount to your plans, plan subscriptions, Olares memberships, and more. ::: tip NOTE Trial credits or coupons are non-refundable. If you request a refund, the system will only refund your actual payment. ::: ## FAQs ### Will I be charged if someone accesses the WordPress site deployed on Olares? Yes, charges will occur from both Cloudflare for the traffic going through Cloudflare FRP tunnel. It mainly helps to hide the real IP of Olares and provides security protection against Distributed Denial of Service (DDoS) and other threats. If you host Olares on the cloud, traffic fee from your chosen vendor will apply. ### What happens if my bill is less than $1? If your total bill is under $1, it won't trigger a card charge. Instead, this amount will be added to your balance and rolled into the next bill. ### How do I resolve a negative balance? A negative balance doesn't always mean you owe money. If you have a negative balance, check the **Billing** > **Balance** section for details. Pay any outstanding amounts to avoid service interruptions. --- ### Space Create Olares (`docs/space/create-olares.md`) --- outline: [2, 3] description: Set up your cloud based Olares instance in Olares Space. Configure system resources, monitor installation progress, and activate your instance with proper credentials. --- # Create a cloud-based Olares Cloud-based Olares offer a convenient deployment option, enabling you to set up an Olares environment without managing hardware directly. This section provides a step-by-step guide to creating and managing your cloud-based Olares. ::: tip NOTE - The **Host Service** is currently in an invite-only beta phase. To access the cloud-based Olares, contact us for an invitation. - If you are looking for information about setting up a self-hosted Olares, refer to the [Getting Started Guide](../manual/get-started/index.md). ::: ## Prerequisites Ensure you get an Olares ID to log in to Olares Space and activate the Olares instance. ## Create an Olares 1. Log in to [Olares Space](https://space.olares.com/) by scanning the QR code using LarePass. 2. Navigate to the **Cluster** page and select the second option to start creating. 3. Configure the environment for installation as below: - **Select Cloud Provider**: Choose a cloud service provider and the data center location closest to your users or workloads. - **Hardware Configuration**: Select the instance's CPU, RAM, and storage resources. - **Olares Version & Kubernetes Setup**: Choose the appropriate version of Olares and the Kubernetes/K3S solution to be installed. :::tip If you intend to host large language models (LLMs), select the **Alibaba Cloud Hong Kong** region. Currently, it is the only region that offers instances with shared GPU services. ::: 4. Review the fees for storage and traffic. ::: tip NOTE Each instance comes with a set amount of free storage and bandwidth. If your usage exceeds these quotas, additional fees will apply based on your cloud provider's pricing. ::: 5. Review your order details, including instance configuration, selected options, and fees. 6. Complete the payment to initiate the installation process. ## Monitor installation The creation and installation of your cloud-based Olares typically take around 10 minutes. During this time, you can monitor the progress and logs in real-time. ### System statuses The installation follows several key stages, represented by different statuses: | Status | Description | |------------------------|-------------------------------------------------------------------------------| | **Unpaid** | Instance created but pending payment. Can be canceled. | | **Fetching** | Payment confirmed. System is creating resources. | | **Queuing** | Resource creation request has been submitted. | | **Pending** | Resources created. Waiting for OS installation. | | **Installing** | OS installation is in progress. | | **Restoring** | OS restoration is in progress from backup. | | **Restore_error** | Restoration failed because of incorrect snapshot password. | | **Restarting** | System is restarting. | | **Stopping** | System is shutting down. | | **Starting** | System is starting up. | | **Running** | System is operating normally. You can restart, stop, or destroy the instance. | | **Stopped** | System is not running. You can restart or destroy the instance. | | **Errored** | System encountered an error during resource creation or installation. | | **Destroying** | Instance is being destroyed. | | **Destroyed** | Instance has been destroyed. | | **Canceled** | Instance is terminated due to cancellation or payment issues. | | **Pending Activation** | System is waiting for activation. Will start after activations. | ### Real-time logs Click **Log** to view detailed logs and monitor the installation process in real time. ## Activate Olares When the installation enters the **Pending Activation** state, activate Olares: 1. Click **Activation**. A pop-up window will display Olares ID, one-time password, and a wizard URL. 2. Access the wizard URL in your browser, and use the one-time password to log into Olares for the first time. 3. Change the Olares password via LarePass when prompted. 4. Follow the on-screen instructions to finish the rest of activation process. --- ### Space Host Domain (`docs/space/host-domain.md`) --- outline: [2, 3] description: Set up custom domains in Olares Space with domain verification and DNS configuration. Create organizational Olares IDs and manage domain settings for your team. --- # Set up a custom domain Whether you're an organizational user wanting employees to use a company-specific domain for login, or you simply wish to use a domain that you own, Olares Space allows you to set up a custom domain for easy access. This guide walks you through adding your own domain for your Olares system on Olares Space. ## Prerequisites ::: tip NOTE A new domain can only be bound if the account is in the DID stage. If the account has already been bound with an Olares ID, it means that the account is already associated with a Domain. ::: Before creating and configuring your own domain, make sure that: - **DID account status**: Ensure your account is in DID status (i.e., not yet bound to an Olares ID). - **Domain Name**: Ensure you have a domain name registered through a domain registrar. The domain should not already be bound to another account in Olares Space. - **LarePass app**: Make sure the LarePass app is installed on your phone, as it is required for Verifiable Credential and domain management tasks. - **Access to the DNS settings of your domain**: This is for configuring the TXT record and NS record. ## Add your domain When you have everything ready, take the steps below to add your domain in Olares Space. 1. In the Olares Space console, navigate to **Domain** > **Domain Name Setup**, and enter your custom domain as instructed. 2. Add a TXT record for your domain to confirm your domain ownership. The system will verify your configuration. Once verified, the domain setup status will update automatically to **Await NS Record for Your Domain**. 3. Add NS records to allow Olares Space to configure DNS for your domain. The system will verify your configuration. Once verified, the domain status will update to **Awaiting the application for the domain's Verifiable Credential**. 4. Launch your LarePass app, and navigate to **Organization Olares ID** > **Create an Organization**. You should see your domain listed. 5. Click on the domain name to store the domain name on blockchain. When it's done, the domain setup status should change to **Awaiting rule configuration** on Olares Space. So far you have successfully associated your domain with your DID. You can now continue to [set the email invitation rule](manage-domain.md#set-email-invitation-rules) and create an organization Olares ID using the domain. ## Create an Org Olares ID Now that your organization has a verified domain name, you or other members you invite can create an Olares ID using this domain. 1. In the LarePass app, navigate to **Organization Olares ID** > **Join an existing organization**. 2. Enter your organization's domain name and click **Continue**. Recheck whether your domain name has been verified and configured if an error occurs. 3. Bind the VC via your email accounts. Currently, only Gmail and Google Workspace email are supported. Upon completion, you will receive an Organization Olares ID. Now you can go ahead to [Activate Olares](../manual/get-started/activate-olares). ## Domain status and processing After submitting a domain name, several steps are necessary to validate the entered domain. The table below explains different domain statuses and the corresponding actions required: | Status | Action Required | |-----------------------------------------------------------------|---------------------------------------------------------------| | Awaiting TXT record configuration | Add a TXT record | | Awaiting NS record configuration | Add NS records | | Awaiting the application for the domain's Verifiable Credential | Complete blockchain domain application on mobile | | Awaiting submission of the domain's Verifiable Presentation | Complete blockchain domain application on mobile | | Awaiting rule configuration | Set up email invitation rules for organization members | | Binding | Wait for binding with Olares, you can access the details page | | Allocated | Bound to Olares, you can access the details page | --- ### Space Manage Accounts (`docs/space/manage-accounts.md`) --- description: Learn how to access and manage Olares Space accounts using LarePass authentication. --- # Manage accounts in Olares Space This guide walks you through common account operations with Olares Space, including logging in, managing multiple accounts, and logging out. ## Log in to Olares Space Olares Space uses a decentralized ID (DID) or Olares ID for authentication. Make sure you already have obtained your credentials on your LarePass. 1. In the LarePass app, select the DID or Olares ID you wish to use to log in. 2. Open https://space.olares.com/ in your browser. 3. Scan the QR code using LarePass. ::: tip NOTE The features and services available on Olares Space vary depending on whether you use a DID or Olares ID for login. - **Logging in with a DID** allows you to set your own domain since no domain is associated to the account. However, you must bind the DID to an Olares ID before you can activate an Olares device. - **Logging in with an Olares ID** enables you to create an Olares, provided the name isn't already linked to another Olares device. However, you cannot use your custom domain since your Olares ID already corresponds to a unique domain. ::: ## Log out To log out of your account: 1. Click your avatar in the top-right corner. 2. Select **Log Out**. Alternatively, you can: 1. Choose **Switch Account** from the menu. 2. Click logout next to any listed account. ## Manage multiple accounts Each Olares ID is linked to only one Olares. With multi-account management in Olares Space, you can switch between accounts effortlessly — perfect for managing multiple Olares IDs and instances. To add an account: 1. Click your avatar in the top-right corner. 2. In the pop-up menu, select **Import Account**. 3. Launch LarePass, and scan the QR code to log in. Once you've added multiple accounts, switch between them using the **Switch Account** option in the menu. If the account is logged out, you'll be redirected to the QR code login page. --- ### Space Manage Domain (`docs/space/manage-domain.md`) --- outline: [2, 3] description: Configure domain settings in Olares Space with email invitation rules and member management. Administrate organizational Olares IDs for seamless team collaboration. --- # Manage your domain You must [add a domain](host-domain.md#add-your-domain) before managing it. Once your domain is set up, you can configure email invitation rules for organization members and invite them to create their own organizational **Olares ID** via email. ## Set email invitation rules Most companies use a standard domain suffix for their team members' emails, like `A@myteam.com` for person A or `B@myteam.com` for person B. However, sometimes, team members might use emails in different domains. To accommodate these scenarios, Olares provides two types of rules for adding organization members' emails: - **Fixed email suffix**: Use this option when all team members share the same email domain. Enter your organization's domain suffix (example: @company.com). Any email matching this suffix can be associated with your organization's Olares ID. - **Specified email address**: Use this option if your organization doesn't have a corporate email suffix. You need to manually add the email address for each member of the organization. :::info NOTE - Currently, only Gmail is supported for both rule types. - Emails that have been used to create organizational Olares IDs will appear in the member list and cannot be deleted. - Emails that are manually added and have not been used to create the Olares ID appear as "unbound" and can be removed. ::: ## Manage members After setting email rules, you can add or remove members under your organization. ### Add a member To add a member: 1. On the domain management page, add members to the organization by entering their email address. 2. Notify the corresponding users to use their email addresses to [create an organizational Olares ID](host-domain.md#create-an-org-olares-id). ### Remove a member You can remove email addresses that haven't been used to create an Olares ID. Once an email address is associated with an organization's Olares ID, it cannot be removed. --- ### Space Manage Olares (`docs/space/manage-olares.md`) --- outline: [2, 3] description: Control your Olares instances through system monitoring, worker node management, and shared GPU solutions. Track storage usage, traffic consumption and maintain instance health. --- # Manage Olares This page covers Olares management tasks in Olares Space, including monitoring system data, adding worker nodes, and managing cloud services. ## View system status You can monitor the system status of Olares through **Olares Space**: 1. In your LarePass app, go to **Settings** > **Integration**. 2. Click add in the top right corner and link your Olares Space account to the Olares device. This authorizes Olares Space's access to your system data. 3. Log into [**Olares Space**](https://space.olares.com/). 4. On the **Olares** page, view **Storage usage** and **Traffic consumption** in the system panel. :::info For self-hosted Olares users, it's important to monitor **Traffic statistics** for intranet penetration services, and **Storage usage** for backup services. These services may incur charges based on usage. ::: ## Add worker nodes For cloud Olares users, you can improve performance by adding worker nodes: 1. Click more_horiz in the upper right corner, and select **Add Worker**. 2. On the guide page, choose your preferred hardware configuration. 3. Review the fees for storage and traffic. 4. Confirm your order and submit. ## Return Olares If you no longer need your Olares service, you can return the instance by following these steps: 1. Click more_horiz in the upper right corner. 2. Select **Destroy Olares**. 3. Confirm the action and settle your usage: - If you are eligible for a refund, the amount will be credited back to your account balance. - If additional payment is required, please confirm and settle the payment. ## Shared GPU solution Currently, we do not offer cloud instances that include GPUs. However, for users who need GPU capabilities, we provide a shared GPU solution via rCuda. This solution is ideal for applications like Stable Diffusion, costing approximately $0.02 per image. ::: tip NOTE For Large Language Models (LLMs), the shared GPU solution is still under development and may require further enhancements. ::: If you need GPU support, please reach us on [Discord](https://discord.com/invite/BzfqrgQPDK). --- ### Use Cases Comfyui For Krita (`docs/use-cases/comfyui-for-krita.md`) --- description: Learn how to integrate ComfyUI with Krita for AI-powered digital art creation. Step-by-step guide to setting up and connecting ComfyUI in Olares with Krita for seamless creative workflows. --- # AI art creation with ComfyUI and Krita Running ComfyUI locally on Olares gives you the flexibility of server-side AI processing, but making it work seamlessly with your creative tools requires additional steps. Instead of confining ComfyUI to a single device, Olares allows you to extend its functionality to other machines, enabling smooth integration with tools such as Krita for editing and refinement. This tutorial will show you how to connect a locally hosted ComfyUI instance on Olares to Krita running on a separate computer. By combining the power of ComfyUI with Krita, you'll be able to create a streamlined, AI-driven workflow that fits naturally into your creative process. ## Objectives In this tutorial, you will learn how to: - Deploy and configure ComfyUI in Olares to maximize performance and resource efficiency. - Integrate ComfyUI with Krita to create AI-generated artwork seamlessly. ## Understanding the components Your AI art studio consists of three key pieces working together: * **ComfyUI**: The AI engine running in your Olares environment that powers image generation. * **Krita**: Professional-grade digital art software where you'll create and edit your artwork. * **Krita AI Diffusion Plugin**: The connector that enables seamless communication between Krita and ComfyUI. ## What you'll need Before starting, ensure you have: * A working Olares installation with internet access * A computer connected to the same local network as Olares * Sufficient system resources (recommended: 16GB RAM for optimal performance) ## Set up ComfyUI 1. Install ComfyUI Shared from Market. - For administrator users, this installs both ComfyUI Launcher (the management UI) and ComfyUI (the client UI). - For member users, this only installs ComfyUI. {width=40%} 2. The administrator configures and launches the ComfyUI service from the ComfyUI Launcher. 3. Configure ComfyUI access policy. a. Open Settings, navigate to **Applications** > **ComfyUI Shared** > **Entrances**. b. Set the **Authentication level** for ComfyUI to **Internal**. {width=70%} 4. Launch ComfyUI from your desktop, and verify the installation by generating a sample image. 5. Copy the address of ComfyUI for next steps. :::tip For security, you should always run AI applications within your local network. When properly configured, your ComfyUI URL should contain `.local`. If `.local` is missing, check your local network environment and make sure no external network proxy service is enabled. ::: ## Set up Krita 1. Download [Krita](https://krita.org/en/download/). 2. Download the [Krita AI Diffusion plugin](https://github.com/Acly/krita-ai-diffusion/releases). 3. Launch Krita, and navigate to **Tools** > **Scripts** > **Import Python Plugin from File**, and select the downloaded ZIP package. {width=70%} 4. Confirm the plugin activation and restart Krita. 5. Open Krita, and verify the installation in **Settings** > **Configure Krita** > **Python Plugin Manager**. ## Connect Krita to ComfyUI Establish a secure connection between Krita and ComfyUI: 1. Create a new document in Krita. :::tip Start with a 512 x 512 pixel canvas to optimize performance and manage graphics memory efficiently. ::: 2. Click **Settings** > **Dockers** > **AI Image Generation** to enable the plugin. You could position the panel to where it's convenient. 3. Click **Configure** to access the plugin settings. {width=70%} 4. Set up ComfyUI connection. a. In **Connection**, select **Custom Server**, and paste your ComfyUI URL. b. Click **Connect** to verify the connection. A green "Connected" indicator confirms successful connection. :::info If connection fails: - Verify network connectivity between your computer and Olares. - Confirm ComfyUI's authentication level is set to "Internal". - Check for and disable any interfering proxy services. - Ensure ComfyUI is running correctly on your Olares. ::: 5. Adjust ComfyUI settings. a. In **Styles**, configure your preferred style templates and select appropriate model checkpoints. b. Keep default values for other settings unless you need specific optimizations. ## Create AI art with text prompts Now comes the exciting part - creating AI-generated artwork using natural language prompts. 1. Enter your prompts in the text box, and click **Generate**. 2. Browse through the generated image variations. 3. Select a preferred result, and click **Apply** to save it to the canvas. :::tip If the results aren't quite what you want, you could: - Create additional variations with new generations. - Fine-tune the generation parameters. - Refine your text prompt for more precise results. - Experiment with different style settings. ::: --- ### Use Cases Comfyui Launcher (`docs/use-cases/comfyui-launcher.md`) --- description: Administrators' guide on how to manage ComfyUI on Olares using ComfyUI Launcher, covering controling the service, managing models, plugins, and python environments, troubleshooting and maintenance. --- # Manage ComfyUI using ComfyUI Launcher ComfyUI Launcher is the core management tool of ComfyUI for **administrator users**. You can use it to control the running status of the ComfyUI service within the cluster, while easily managing models, plugins, runtime environment, and network configurations. This document guides you on how to use ComfyUI Launcher for ComfyUI service management and routine maintenance. ## Start and stop the ComfyUI service As the administrator, you must start the ComfyUI service before you and other members can access it using the client interface. * **Start the ComfyUI Service**: Click the **START** button in the upper-right corner to start the ComfyUI service. ::: tip Notes on first run * Initial startup of ComfyUI Launcher typically takes 10-20 seconds for environment initialization. * If the system prompts that essential models are missing, you can click the **START ANYWAY** button to launch the service. However, note that workflows may not run correctly if basic models are missing. It is recommended to download the essential model package before starting the service. ::: * **Stop the ComfyUI Service**: If you are not using ComfyUI for the moment, click the **STOP** button to stop the service. This releases the VRAM and memory resources occupied by ComfyUI. ## Manage models :::tip Note Before installing models, ensure your host can access GitHub and HuggingFace. For details, refer to [Configure network](#configure-network). ::: ComfyUI Launcher provides flexible ways to install models. You can install the essential models with one click, manually install from Hugging Face, or copy from external sources. ### Install essential models Essential models are basic models required for ComfyUI to run, including SD large models, VAE, preview decoders, and auxiliary tools models. It is recommended to install the essential package when running ComfyUI for the first time. 1. Access the essential model package page in either of the following methods: - In the **Missing essential models** prompt window that appears when starting the service for the first time, click **INSTALL MODELS**. * In the **Package installation** section on the homepage, find **Essential model package**, and click **VIEW**. 2. On the essential model installation page, click **GET ALL RESOURCES** to start the automatic installation. You can view the installation status via the progress bar below. ### Manually download models In addition to the essential models, ComfyUI Launcher also supports downloading models from the HuggingFace model library, allowing you to easily get the models you need. :::tip Upload external models If you can't find the desired model on Hugging Face, you can use **Files** to upload external models to the following directory: `External Devices/ai/model` ::: ### Delete a model To delete a model: 1. Navigate to **Model management** > **Model library**. 2. Under the **Installed models** section, find the model you want to delete, and click the delete button on the right to delete it permanently. ## Manage plugins You can manage plugins through ComfyUI's built-in ComfyUI-Manager or use **Plugin management** in the Launcher. ### Manage available plugins To manage available plugins registered in ComfyUI Manager: 1. Navigate to **Plugin management** > **Plugin Library**. 2. Under **Available plugins**, select the target plugin: * Click the pause button to disable the currently running plugin, and click the play_circle button to resume running. * Click the delete button to delete the plugin. * Click the download button to download the plugin. * Click the visibility button to view plugin details. * Click the **UPDATE ALL PLUGINS** button to update all installed plugins. * Click the **REFRESH** button to refresh the plugin status. ### Download plugin from GitHub To install plugins directly from GitHub repositories: 1. Navigate to **Plugin management** > **Custom Install**. 2. Enter the URL of the repository. 3. Specify the branch (optional). Use the default (usually 'main' or 'master') if not specified. 4. Click **INSTALL PLUGIN**. ## Manage Python environment ComfyUI's operation relies on a set of complex Python dependency libraries. You can manage these libraries easily on the **Python dependency management** page. ### Install new dependency libraries To install a new dependency library: 1. Navigate to **Python dependencies**. 2. click **INSTALL NEW PACKAGE**. 3. In the pop-up window, enter the library name and version number (optional), and then click **INSTALL**. ### Manage installed dependency libraries 1. Under **Installed Python packages**, find the Python library you want to manage. 2. Click the arrow_upward button on the right to update the library, or the delete button to remove it. ### Analyze dependency installation status 1. Under the **Dependency analysis** tab, click **ANALYZE NOW** to start analyzing. 2. From the plugins list on the left, find the problematic plugin highlighted in red, and click on it. 3. From **Dependency list**, find the missing library for the plugin, and click the **Install** button on the right. You can also click **FIX ALL** to automatically install all missing libraries. ## Troubleshooting and maintenance ComfyUI Launcher provides tools to help diagnose and maintain the ComfyUI service. ### Configure network Network connection issues can affect the download of models and plugins. Before using ComfyUI, it's recommended to check the connection status to GitHub, PyPI, and HuggingFace on the Launcher homepage. For example, if GitHub is inaccessible: 1. Navigate to the **Network configuration**. 2. Switch the provided URLs for GitHub. 3. Click the **CHECK** button on the right to refresh the connection status. Repeat steps 2 and 3 until the network becomes "Accessible". ### Export ComfyUI logs You can export logs to diagnose the current running status of ComfyUI: 1. In the upper-right corner of the Launcher homepage, click more_vert, then click **View logs** to view the current running log. 2. Click the refresh button to refresh the log, and the download button to download the log. ### Reset ComfyUI configuration To reset ComfyUI to its initial state: 1. In the upper-right corner of the Launcher's homepage, click more_vert, and select **Wipe and restore**. After a second confirmation, the Launcher will begin the wiping and restoration process. 2. After the restoration operation is complete, restart ComfyUI for the changes to take effect. :::warning Exercise caution Restoring ComfyUI is an irreversible operation. Please operate carefully. ::: ## Discover inspirations Enter the **Discover** page from the left sidebar to view the latest and most trending ComfyUI models and workflows on [civit.ai](civit.ai). ::: tip Note Please ensure your network can properly access [civit.ai](civit.ai). ::: --- ### Use Cases Comfyui (`docs/use-cases/comfyui.md`) --- description: Discover how to install ComfyUI, a node-based interface for Stable Diffusion, with ease in Olares. Create reusable workflows, fine-tune image generation, and apply advanced post-processing effects. --- # ComfyUI ComfyUI is a powerful node-based interface for Stable Diffusion that transforms AI image generation into a visual programming experience. By connecting different nodes together like building blocks, you gain precise control over every aspect of the generation process - from prompts and models to post-processing effects. Unlike the straightforward interface of SD Web UI, ComfyUI lets you create custom workflows by connecting nodes that represent different operations. This approach gives you deeper control over the image generation pipeline while making complex operations reusable and shareable. ## What can ComfyUI do? ComfyUI puts advanced AI image generation capabilities at your fingertips: * Create reusable workflows by connecting nodes visually * Fine-tune every aspect of the generation process * Mix and match different models and techniques * Save and share your custom workflows with others * Batch process images with consistent settings * Apply advanced post-processing effects ## Install ComfyUI Shared Olares provides ComfyUI Shared to allow multiple users to share models, plugins, and workflow resources within the cluster. It also features ComfyUI Launcher, providing administrator users with a simple way to manage ComfyUI resources and runtime environments. ::: tip Note Starting from Olares 1.11.6, Shared applications will replace previous cluster-scoped applications. If you have installed ComfyUI for Cluster and its client, please uninstall them before installing ComfyUI Shared. ::: To install ComfyUI Shared: 1. Open Olares Market, find **ComfyUI Shared**, and click **Get**. - The administrator will see two icons on the Olares desktop: one is the client interface for ComfyUI, and the other is ComfyUI Launcher. {width=40%} - Member users will only see the ComfyUI client interface on the desktop. :::tip Start the ComfyUI service The administrator must start the ComfyUI service from the Launcher before all users in the cluster can access the service from the client interface. ::: 2. Click the ComfyUI icon to open the interface. Administrators can also enter the ComfyUI interface from the Launcher. ## Learn more * [Manage ComfyUI using ComfyUI Launcher](comfyui-launcher.md) * [Krita + ComfyUI Real-time Painting](comfyui-for-krita.md): Learn how to leverage ComfyUI to assist creative workflows in Krita. --- ### Use Cases Dify (`docs/use-cases/dify.md`) --- description: Guide to leveraging Dify on Olares for building AI applications. Learn how to deploy Dify and add personal knowledge base with ease. --- # Customize your local AI assistant using Dify Dify is an AI application development platform. It's one of the key open-source projects that Olares integrates to help you build and manage AI applications while maintaining full data ownership. Additionally, you can integrate your personal knowledge base documents into Dify for more personalized interactions. ## Before you begin To use local AI models on Dify, ensure you have: - [Ollama installed](ollama.md) and running in your Olares environment. - [Open WebUI installed](openwebui.md) with your preferred language models downloaded. :::tip For optimal performance, consider using lightweight yet powerful models like `gemma2` or `qwen`, which offer a good balance between speed and capability. ::: ## Install Dify :::info Starting from Olares 1.11.6, if "Dify For Cluster" or "Dify" was previously installed, uninstall them before proceeding. ::: 1. Install "Dify Shared" from Olares Market. 2. Launch Dify from your desktop. Please ensure the admin has already installed Dify Shared. ## Create an AI assistant app 1. Open Dify, navigate to the **Studio** tab, and select **Create from Blank** to create an app for the AI assistant. Here, we created an agent named "Ashia". 2. Click **Go to settings** on the right to access the model provider configuration page. You can choose between remote models or locally hosted models. ## Add Ollama as model provider 1. Navigate to **Settings** > **Application** > **Ollama** > **Entrances**, and set the authentication level for Ollama to **Internal**. This configuration allows other applications to access Ollama services within the local network without authentication. 2. In Dify, navigate to **Settings** > **Model Provider**. 3. Select Ollama as the model provider, with the following configurations: - **Model Name**: Enter the model name. For example: `gemma2`. - **Base URL**: Enter Ollama's local address: `https://39975b9a1.local.{username}.olares.com`. Replace `{username}` with the Olares Admin's local name. For example, `https://39975b9a1.local.marvin123.olares.com`. {width=70%} :::tip You can keep default values for other required fields. ::: 4. Click **Save**. ## Configure Ashia 1. Navigate to Dify's **Studio** tab and enter Ashia. 2. From the model list on the right, select the Gemma2 model you just configured. 3. Click **Publish**. Now you can chat with Ashia in the **Debug & Preview** window. ## Set up local knowledge base 1. In Dify, navigate to the **Knowledge** tab. 2. Locate your default knowledge base. It will be named after your Olares ID and monitors the `/Documents` folder in Files. 3. Enter `/Documents` and add documents to the knowledge base. 4. In Ashia's orchestration page, click **addAdd** to add context support for Ashia. {width=70%} 5. Click **Publish**. Now try asking a domain-specific question with the help of the knowledge base. --- ### Use Cases Host Cloud Android (`docs/use-cases/host-cloud-android.md`) --- outline: [2, 3] description: Deploy a cloud Android emulator using redroid on Olares, and access the Android host from macOS and Windows via adb and scrcpy. --- # Host your cloud Android with redroid [redroid](https://github.com/remote-android/redroid-doc) (Remote Android) is a GPU-accelerated Android-in-Cloud (AIC) solution that integrates seamlessly with Olares. You can easily host high-performance Android instances on your Olares and access them anytime to run Android games, apps, or even automation tests. This tutorial walks you through installing redroid on Olares and accessing the Android instance from Windows and macOS. ## Objectives By the end of this tutorial, you will learn how to: - Install the required Linux kernel modules on the Olares host. - Install the redroid app on Olares and get the service URL. - Connect and operate the Android instance from Windows and macOS, using `adb` and `scrcpy`. - Install APK apps on the Android instance. ## Before you begin Make sure the following requirements are met: - Olares is installed and running on a Linux machine. ::: tip Configuration requirements - redroid is only supported on Linux. Make sure your Olares instance is running on a Linux system. - redroid is resource-intensive. For best performance, we recommend using a machine with at least an 8-core CPU and 16GB of RAM. ::: - Your device and Olares are on the same local network. :::tip Remote access If your device is on a different network, use [LarePass](https://olares.com/larepass) to enable a private network connection to Olares. ::: ## Install dependent kernel modules redroid requires specific kernel modules to run on Linux. For details, refer to the [official redroid docs](https://github.com/remote-android/redroid-doc/blob/master/deploy/README.md). For example, on Ubuntu, you can install the required kernel modules by running the following commands in the terminal: ```bash sudo apt install linux-modules-extra-`uname -r` sudo modprobe binder_linux devices="binder,hwbinder,vndbinder" # This command might fail on newer kernels; the error can be safely ignored. sudo modprobe ashmem_linux ``` ## Install redroid on Olares redroid runs as a headless backend on Olares. To install redroid: 1. In Olares Market, find redroid under "Utilities", and click **Get**. redroid will launch automatically after installation. 2. Get the URL to access the redroid service: a. From Olares Desktop, navigate to **Settings** > **Application** > **redroid**. b. In **Entrances** > **Set up endpoint**, get the base domain of redroid, e.g., `beb583c3..olares.com`. c. Append the exported port of redroid (`46878`) to the base domain. As redroid only allows local access, the domain should also include `.local`. Here is an example of our final URL to access the redroid service: `beb583c3.local.olares01.olares.com:46878`. ## Connect to the redroid service To access the Android instance on Olares, you'll need to connect to the redroid service using `adb` and render the UI using `scrcpy`. ## Install APK Once connected, you can use `adb` to install third-party APK apps on the Android instance. After installation, run `scrcpy` again to render the Android screen. Swipe up to see the installed APK. ## Common `adb` commands :::tip Note The following commands are for macOS and Linux. On Windows, replace `adb` with `adb.exe`. ::: ```bash # Start adb server adb start-server # Connect to a device adb connect : # List connected devices adb devices # Disconnect a device adb disconnect : # Install an APK by transport_id adb -t 3 install your_app.apk # View real-time logs adb logcat # Export logs to a file adb logcat -v time > log.txt # Push a file to the device adb push # Pull a file from the device adb pull # List directory contents on device adb shell ls # View file contents adb shell cat # Reboot the device adb shell reboot # Shut down the device adb shell reboot -p ``` --- ### Use Cases Ollama (`docs/use-cases/ollama.md`) --- outline: [2, 3] description: Learn how to download and manage AI models locally using Ollama CLI within the Olares environment. --- # Download and run AI models locally via Ollama Ollama is a lightweight platform that allows you to run open-source AI models like `deepseek-r1` and `gemma3` directly on your machine. Within Olares, you can integrate Ollama with graphical interfaces like Open WebUI to add more features and simplify interactions. This guide will show you how to set up and use Ollama CLI on Olares. ## Before you begin Before you start, ensure that: - You have Olares admin privileges. ## Install Ollama Directly install Ollama from the Market. Once installation is complete, you can access Ollama terminal from the Launchpad. ## Ollama CLI Ollama CLI allows you to manage and interact with AI models directly. Below are the key commands and their usage: ### Download model :::tip Check Ollama library If you are unsure which model to download, check the [Ollama Library](https://ollama.com/library) to explore available models. ::: To download a model, use the following command: ```bash ollama pull [model] ``` ### Run model :::tip If the specified model has not been downloaded yet, the `ollama run` command will automatically download it before running. ::: To run a model, use the following command: ```bash ollama run [model] ``` After running the command, you can enter queries directly into the CLI, and the model will generate responses. When you're finished interacting with the model, type: ```bash /bye ``` This will exit the session and return you to the standard terminal interface. ### Stop model To stop a model that is currently running, use the following command: ```bash ollama stop [model] ``` ### List models To view all models installed on your system, use: ```bash ollama list ``` ### Remove a model If you need to delete a model, you can use the following command: ```bash ollama rm [model] ``` ### Show information for a model To display detailed information about a model, use: ```bash ollama show [model] ``` ### List running models To see all currently running models, use: ```bash ollama ps ``` ## Learn more - [Learn how to run Ollama models with Open WebUI](openwebui.md) --- ### Use Cases Openwebui (`docs/use-cases/openwebui.md`) --- outline: [2, 3] description: Guide to using Open WebUI in Olares for managing Large Language Models. Learn about model management, voice interactions, and image generation capabilities with both Ollama and OpenAI-compatible APIs. --- # Open WebUI Open WebUI provides an intuitive interface for managing Large Language Models (LLMs) that supports both Ollama and OpenAI-compatible APIs. This page helps you set up and configure Open WebUI in Olares for: * Model management * Voice interactions (speech-to-text and text-to-speech) * Image generation capabilities ## Installation Ollama is required prior to launching Open WebUI: * **For admin**: Install both "Ollama" and "Open WebUI". * **For team members**: Ensure that "Ollama" is already installed by Olares admin, and then install "Open WebUI" only. {width=30%} :::info First-time users need to create a local Open WebUI account. This account is specifically for your Olares installation and doesn't connect to external services. Note that existing Open WebUI accounts from other installations cannot be used here - you'll need to create a new one. ::: ## Download models :::tip Browse available models on [Hugging Face's Chatbot Arena Leaderboard](https://huggingface.co/spaces/lmsys/chatbot-arena-leaderboard) and verify model names in the [Ollama Library](https://ollama.com/library) before downloading. ::: Recommended starter models for optimal performance (13B parameters or smaller): * `gemma2`: Google's latest efficient and powerful language model * `llama3.2`: Meta's latest open-source vision-language model ### Quick download 1. Click the dropdown menu, enter the model name (e.g., `llama3.2`). 2. Select **Pull from Ollama.com**. The download starts automatically. ### Download from settings 1. Click your username in the bottom left. 2. Navigate to **Admin Panel** > **Settings** > **Models**. 3. Under **Pull a model from Ollama.com**, enter the model name (e.g., `llama3.2`). 4. Click download to initiate the download. ## Configure speech features ### Speech-to-text 1. Install Faster Whisper from Market based on your role: - Admin: Install both "Faster Whisper For Cluster" and "Faster Whisper". - Team members: Ensure that "Faster Whisper For Cluster" is already installed by Olares admin, and install "Faster Whisper" only. {width=40%} 2. Open WebUI, and navigate to **Admin Panel** > **Settings** > **Audio**. 3. Select **OpenAI** as the speech-to-text engine, with the following configurations: - API Base URL: `http://whisper.whisper-{admin's local name}:8000/v1`. For example: `http://whisper.whisper-alice123:8000/v1`. - API key: enter any character. 4. Enter a model variant (default: `whisper-1`). You can select from the following: - `tiny.en` - `tiny` - `base.en` - `base` - `small.en` - `small` - `medium.en` - `medium` - `large-v1` - `large-v2` - `large-v3` - `large` - `distil-large-v2` - `distil-medium.en` - `distil-small.en` - `distil-large-v3` 5. Click **Save**. 6. Launch Faster Whisper after configuration. You'll see that the model you configured in Open WebUI is automatically loaded. At this point, you can either: - Upload audio directly to start transcription - Adjust parameters including: - Select different sub-models - Choose task types - Configure **Temperature** settings ### Text-to-speech 1. The admin installs OpenedAI Speech from Market. This launches the service within the cluster. :::info "OpenedAI Speech" is a shared application and can only be installed by Olares admin. If you are a team member, ensure that the Olares admin has already installed "OpenedAI Speech". 2. Open WebUI, and navigate to **Admin Panel** > **Settings** > **Audio**. 3. Select OpenAI as the text-to-speech engine, with the following configurations: - API Base URL: `http://openedaispeech.openedaispeech-{admin's local name}:8000/v1`. For example: `http://openedaispeech.openedaispeech-alice123:8000/v1`. - API key: enter any character. 4. Click **Save**. ### Text-to-image With [SD Web UI Shared installed in your Olares environment](stable-diffusion.md#install-sd-web-ui), you can leverage Stable Diffusion's powerful image generation capabilities directly through Open WebUI. 1. The admin installs SD Web UI Shared from Market. This launches the Stable Diffusion service within the cluster. 2. Open Open WebUI, and navigate to **Admin Panel** > **Settings** > **Images**. 3. Select **Automatic1111** as the image generation engine, with the base URL: `http://sdwebui.sdwebui--{admin's local name}:7860`. For example: `http://sdwebui.sdwebui-alice123:7860`. 4. Click cached to verify the connection. 5. Turn on **Image Generation (Experimental)**, and select your preferred text-to-image model checkpoint. 6. Click **Save**. --- ### Use Cases Perplexica (`docs/use-cases/perplexica.md`) --- description: Explore Perplexica for advanced AI-driven data analysis and visualization with Olares. Learn how to set up Perplexica with ease. --- # Perplexica Perplexica is an open-source AI-powered search engine that provides intelligent search capabilities while maintaining user privacy. As an alternative to Perplexity AI, it combines advanced machine learning with comprehensive web search functionality to deliver accurate, source-cited answers to your queries. ## The backend: SearSNG SearXNG serves as the privacy-focused meta-search engine backend for Perplexica. It: * Aggregates results from multiple search engines * Removes tracking and preserves your privacy * Provides clean, unbiased search results for the AI model to process This integration enables Perplexica to function as a complete search solution while maintaining the security of your sensitive information. ## Before you begin Before getting started, ensure you have: - Ollama installed and running in your Olares environment - Open WebUI installed with your preferred language models downloaded :::tip For optimal performance, consider using lightweight yet powerful models like `gemma2`, which offer a good balance between speed and capability. ::: ## Set up Perplexica 1. The admin installs SearXNG from Market. :::info Starting from Olares 1.11.6, if "SearXNG For Cluster" or the "SearXNG" client was previously installed, uninstall them before proceeding. ::: 2. Install Perplexica from Market. 3. Launch Perplexica, and click settings in the bottom left corner to open the settings window. 4. Configure your search environment with the following settings (using `gemma2` as an example): - **Chat model Provider**: `Ollama` - **Chat Model**: `gemma2:latest` - **Embedding model Provider**: `Ollama` - **Embedding Model**: `gemma2:latest` {width=50%} 5. Click the confirmation button to save your configuration and return to the search interface. Your setup is complete. Try searching for a topic you're interested in to test your new search environment. --- ### Use Cases Remote.Reusables (`docs/use-cases/remote.reusables.md`) --- search: false --- :::info iOS or macOS versions of LarePass will require adding a VPN configuration file to the system when turning on the VPN. Follow the prompts to complete the setup. ::: --- ### Use Cases Stable Diffusion (`docs/use-cases/stable-diffusion.md`) --- description: Comprehensive guide to using Stable Diffusion in Olares. Learn about text-to-image generation, and how to optimize your SD Web UI deployment for multi-user environments. --- # Stable Diffusion Stable Diffusion represents a groundbreaking implementation of latent diffusion models (LDMs) in AI image synthesis. This deep learning architecture operates by decomposing the image generation process into a lower-dimensional latent space, significantly reducing computational requirements while maintaining high-fidelity output. Olares simplifies the deployment and management of Stable Diffusion. Unlike traditional deployments that require manual configuration of file systems and databases, Olares shields developers from these infrastructure complexities, allowing you to focus solely on using the model for image generation. With Olares's multi-user support, team members can share a single Stable Diffusion deployment while maintaining individual data privacy. This approach eliminates the need for redundant system installations that would otherwise consume excessive hardware resources. ## What can Stable Diffusion do? Whether you're an artist looking to expand your creative toolkit, a developer integrating AI imaging into your workflow, or simply curious about AI art generation, Stable Diffusion offers: * Text-to-image generation * Image-to-image transformation * Inpainting and outpainting capabilities * Style transfer and artistic modifications * High-resolution image creation and upscaling ## Install SD Web UI :::info Starting from Olares 1.11.6, if "SD Web UI For Cluster" or "SD Web UI" was previously installed, uninstall them before proceeding. ::: 1. Install SD Web UI Shared directly from Market. 2. Launch SD Web UI from your desktop. Please ensure the admin has already installed SD Web UI Shared. Now you are ready to unleash your creativity and start generating stunning images! ## Prevent conflicts among members In SD Web UI, checkpoint settings are globally applied to all users by default. When one user switches to a different checkpoint, all subsequent image generations by other users will also use this newly selected checkpoint. To prevent workflow disruptions in multi-user environments, you could specify checkpoints for individual tasks. 1. Global checkpoint 2. Per-task checkpoint ## Adjust system settings When launching SD Web UI, the `--xformers` flag is enabled by default to: - Reduce VRAM usage - Accelerate image generation - Support higher resolution outputs While this optimization allows for higher resolution image generation, it comes with some trade-offs, such as less stylistic variation between generated images, and slightly reduced prompt interpretation accuracy. If you need to remove `--xformers`: :::info Only Olares admin can adjust system parameters through the Control Hub app. ::: 1. Open Control Hub, and navigate to **Browse**. 2. Locate **sdwebui** under the admin's namespace. 3. Under **Deployments**, click **sdwebui**. 4. Click more_vert in the top right corner, and click **Edit YAML**. 5. In the YAML editor, locate `--xformers` and remove it. The default YAML file should look similar to the following. ```yaml {5} env: - name: CLI_ARGS value: >- --allow-code --enable-insecure-extension-access --api --no-hashing --gradio-queue --xformers ``` 6. Click **OK** to apply the system settings. ## Gallery
Image 1 Image 2
Image 3 Image 4
--- ### Use Cases Stream Game (`docs/use-cases/stream-game.md`) --- outline: [2, 3] description: Comprehensive tutorial on streaming Steam games with Olares. Learn to install Steam Headless, configure the streaming service, and stream games on Moonlight from both local and remote networks. --- # Stream your favorite games with Steam Headless Want to enjoy some gaming with the power of Olares? You are all set. With the Steam Headless app, Olares easily transforms into a steam streaming server. You can now play your favorite games on any compatible device via Moonlight or Steam Link. This guide walks you through installing Steam Headless on Olares, configuring the streaming service, and using the Moonlight client to stream your games. ## Objectives By the end of this tutorial, you will learn how to: - Install Steam Headless on Olares and configure compatibility for Windows games on the Steam client. - Configure the streaming service, which involves pairing the Sunshine streaming server with the host on the Moonlight client. - Stream games on the Moonlight client from both local and remote networks. ## Before you begin Before you begin, ensure the following: - Olares is up and running on a machine equipped with an NVIDIA GPU. - Your streaming device has Moonlight installed. Visit the [Moonlight website](https://moonlight-stream.org/) to download and install the appropriate version. - Your streaming device is connected to the same LAN as your Olares. :::tip Remote streaming For remote streaming, install LarePass on your streaming device. You can download the appropriate version from the [LarePass site](https://olares.com/larepass). ::: - You have a valid Steam account to access your games. ## Install Steam Headless 1. In Olares Market, find Steam Headless under the **Entertainment** category, and click **Get**. 2. Open Steam Headless, and then click **Connect** to access the Steam Headless console. 3. In the Steam Headless console, click the **Install** button to install and update the Steam client. Once completed, the Steam login page should appear. 4. Log into your Steam account and complete the initial setup. ::: tip Retry installation upon failures Due to network issues, Steam installation or update may fail. If this happens, go to the top-left menu in Steam console and navigate to **Applications** > **Internet** > **Steam** to reinstall. ::: ## Configure game compatibility Olares runs on a Linux environment. You'll need to enable [Proton](https://github.com/ValveSoftware/Proton), a compatibility layer, to support Windows games. 1. In the Steam client page, navigate to **Steam** > **Settings** in the top left corner. 2. Go to the **Compatibility** tab and check **Enable Steam Play for all other titles**. 3. Restart the Steam client to view your complete game library. ## Configure the streaming service Steam Headless also integrates Sunshine, the streaming server. To stream games using Moonlight, you need to pair the host PC on moonlight with Sunshine. ### Prepare for paring 1. From your Steam client in the browser, get the URL and append `:47990`, for example, `https://139ebc4f0.local..olares.com:47990`. Open this URL to access the Sunshine console page. 2. On your first visit, log in using the default credentials: - Username: `sam` - Password: `password` 3. Click the **Pin** tab to open the pairing page, where you will be prompted to enter the pairing code. ### Add host in Moonlight 1. Open the Moonlight client on your streaming device and click the add_to_queue button in the top-right corner. 2. When promoted to enter the IP address of your host PC, enter the local URL of Steam, for example, `139ebc4f0.local..olares.com`. ::: tip Note Do not include `https://` and make sure to include the `.local` part in the hostname. ::: 3. Click **OK**, and a host icon appears in locked status. 4. Click the host icon to receive a pairing code. ### Complete paring 1. In Sunshine's paring page, enter the pairing code. 2. Enter a name for the device and click **Send** to finish pairing. If successful, you will see the message: "Success! Please check Moonlight to continue". 3. Check the host status in Moonlight. The icon should be active now. ## Stream your game Now you are done with configuring and ready for gaming. ### Stream locally If you are streaming locally from the same network of Olares: 1. Open Moonlight on your streaming device. 2. Click your steam host, and then click the Steam icon to enter the Steam Big Screen mode and play. ### Stream remotely With Olares's VPN feature, you can enjoy a smooth streaming experience even across different networks. To enable the VPN: Once VPN is enabled on your device, simply follow the same instructions as local streaming. ## FAQs ### Why isn't the game displaying in full screen? This could be due to your resolution settings. Try adjusting the resolution: - In Moonlight: adjust in **Settings** > **Basic Settings** > **Resolution and FPS**. - On the Steam console page: adjust in **Applications** > **Settings** > **Display**. ### How do I exit full-screen streaming? To exit streaming in the full-screen mode: - **On Windows**: Use the shortcut combo **Ctrl + Alt + Shift + Q**. - **On Mac**: Use the shortcut combo **Control (^) + Option (⌥) + Shift + Q**. - **On mobile devices**: use the controller button combo **Start + Select + L1 + R1**. After finishing your streaming session, exit the Steam Big Picture mode to release system resources on Olares. ### Where are my downloaded games stored? By default, games are stored at: `/Cache/olares/steam-headless/c0/.steam/debian-installation/steamapps/common` We recommend not changing this default directory. --- ### Use Cases Stream Media (`docs/use-cases/stream-media.md`) --- outline: [2, 3] description: Comprehensive tutorial on streaming media with Olares. Learn to configure VPN access, manage media files through LarePass, and set up Jellyfin for advanced streaming capabilities from anywhere. --- # Stream your media library from anywhere with Olares Olares makes it easy to access and enjoy your personal media library from anywhere, whether you're at home or on the go. With built-in VPN support and media management tools like Jellyfin, you can stream your favorite movies and TV shows securely and seamlessly. This tutorial will guide you through the process of setting up Olares VPN, accessing media files, and configuring Jellyfin for advanced streaming capabilities. ## Objectives In this tutorial, you will learn how to: - Configure Olares VPN to securely access your media library from anywhere with LAN-like performance. - Explore and play video files stored in Olares Files using the LarePass client or a web browser. - Install and set up Jellyfin for media streaming. ## Enable Olares VPN connection To achieve smooth streaming over external networks, enable the Olares VPN connection in LarePass. This ensures all traffic from devices with LarePass installed routes through the dedicated network, providing LAN-like speed and performance. :::tip For different LarePass download options, visit [the official page](https://olares.com/larepass). ::: Once enabled, you can also access your applications using the format: `https://[RouteID].local.[OlaresDomainName]`. Devices with activated VPN will use the VPN connection to access Olares, whether through the LarePass client or a browser. ## Access media files in LarePass After enabling VPN, you can browse media files stored on Olares. ### Access via LarePass Client 1. Open LarePass, and navigate to your media directory containing movies and TV shows in Files. 2. Click on any file to start playback on your computer or mobile device. ### Access from browser 1. Open files from your Olares desktop, or directly using the local address: `https://files.local.[OlaresDomainName]`. 2. Locate your media directory, and click on video files to begin playback. ## Access media files using Jellyfin For advanced media management features like subtitle support and multi-channel audio, install Jellyfin. 1. Open the Market app in Olares and go to the **Entertainment** category. 2. Locate and download Jellyfin. 3. Launch Jellyfin and complete first-time setup: - Set administrator password. - Configure media library directories. 4. Wait for Jellyfin to scan and index your media library. It will automatically fetch metadata including: - Movie posters - Descriptions - Cast information ## Access your media library through Jellyfin clients To stream your media on various devices: 1. Configure Jellyfin authentication. a. Open Settings, and navigate to **Applications** > **Jellyfin** > **Entrances**. b. Set **Authentication level** to **Internal**. 2. Download and install [Jellyfin's official client](https://jellyfin.org/downloads/). 3. Connect clients to your Jellyfin server in Olares. a. In your Jellyfin client, auto-discovery should locate your server for devices on the same network. b. If auto-discovery fails, manually enter the server address from Olares. 4. Log in to Jellyfin client with your credentials. :::tip Keep the VPN connection active for optimal streaming performance when accessing your media library remotely. ::: --- ### Use Cases Wise.Reusables (`docs/use-cases/wise.reusables.md`) --- search: false --- 将你的内容收集到 Wise 后，你可以通过 Olares 的聚合搜索功能进行全文搜索。 ::: info 搜索格式 目前仅支持文档类型内容（PDF、网页文章和 EPUB）的搜索。其他格式将在后续版本中支持。 ::: 1. 点击 Dock 中的 search 打开搜索窗口。 2. 指定搜索范围为 Wise，并输入关键词进行搜索。 :::info 具体步骤可能会因操作系统和浏览器而有所不同。以下以 Safari 为例。 ::: 1. 在浏览器中点击 ios_share，选择 LarePass 为分享对象。你可以： - 在分享选项中选择 LarePass 的图标，或者 - 在**其他操作**栏中选择 **LarePass** LarePass 应用会自动打开并检测待分享页面的内容，并提示是否要添加至 Wise。 2. 点击**确认**添加。 ::: tip 复制 URL 分享 你也可以直接复制网页 URL 并打开 LarePass。LarePass 会自动检测剪贴板中的 URL 和可收藏的内容。 ::: 收集完成后，可以在 Wise 的**库** > **文章**中阅读收集的文章。 --- ### Developer Contribute Olares (`docs/developer/contribute/olares.md`) # Olares ## Directory structure ``` olares |-- apps # olares built-in apps | |-- agent | |-- analytic | |-- market | |-- market-server | |-- argo | |-- desktop | |-- devbox | |-- vault | |-- files | |-- knowledge | |-- nitro | |-- notifications | |-- profile | |-- rss | |-- search | |-- settings | |-- system-apps | |-- wise | |-- wizard |-- build # olares installer | |-- installer | |-- manifest |-- frameworks # system runtime frameworks | |-- app-service | |-- backup-server | |-- bfl | |-- GPU | |-- l4-bfl-proxy | |-- osnode-init | |-- system-server | |-- tapr |-- libs # toolkit libs | |-- fs-lib |-- scripts # scripts for build or package the olares installer |-- third-party # third party libs or apps integrated in olares | |-- authelia | |-- headscale | |-- infisical | |-- juicefs | |-- ks-console | |-- ks-installer | |-- kube-state-metrics | |-- notification-mananger | |-- predixy | |-- redis-cluster-operator | |-- seafile-server | |-- seahub | |-- tailscale ``` ## How to install ``` curl -fsSL https://olares.sh | bash - ``` ## How to build ``` git clone https://github.com/beclab/olares cd olares bash scripts/build.sh ``` Run the above scripts, you will get the debug version installer package `install-wizard-debug.tar.gz` ## How to install debug version ``` mkdir -p /path/to/unpack && cd /path/to/unpack tar zxvf /path/to/olares/install-wizard-debug.tar.gz make install VERSION=0.0.0-DEBUG ``` ## How to uninstall ```bash bash olares-uninstall.sh ``` --- ### Developer Install Activate Olares (`docs/developer/install/activate-olares.md`) --- search: false --- ## Activate Olares Use the Wizard URL and initial one-time password to activate. This process connects the Olares device with your Olares ID using LarePass. 1. Enter the Wizard URL in your browser. You will be directed to the welcome page. Press any key to continue. 2. Enter the one-time password and click **Continue**. 3. Select the system language. 4. Activate Olares using LarePass app. a. Open LarePass app, and tap **Scan QR code** to scan the QR code on the Wizard page and complete the activation. :::warning Same network required To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. ::: b. Reset the login password for Olares by following the on-screen instructions on LarePass. ::: tip Reactivate Olares with the same Olares ID If you have reinstalled Olares, the original instance becomes unavailable. To reactivate Olares with the same Olares ID: 1. Open LarePass on your phone, and you can see a red prompt: "No active Olares found". 2. Tap **Learn more**, then **Reactivate** to enter the QR scan page. 3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares. ::: After successful setup, the LarePass app will automatically go to the home screen, and the Wizard will redirect you to the login page. --- ### Developer Install Additional Installations (`docs/developer/install/additional-installations.md`) --- description: Installation guide for running Olares in containerized or virtual environments on macOS, Windows, PVE, Raspberry Pi, and more. Intended for development and testing only, not for production use. --- # Additional installation options Additional installation options in this section are intended for **development or testing on special containerized or virtual environments** including Linux, macOS, Windows, PVE, or Raspberry Pi. :::tip Recommendation for production environment Olares is optimized for Linux systems (Ubuntu or Debian). We recommend [installing Olares on Linux using script](../../manual/get-started/install-olares.md) to get the best performance and reliability for production use. ::: To run Olares, you must [create an Olares ID](../../manual/get-started/create-olares-id.md), and ensure that both the operating system and hardware meet the minimum requirements. Choose your preferred option to get started: - [Install on Linx using Docker](linux-via-docker-compose.md) - [Install on macOS](/developer/install/mac) - [Install on Windows (WSL 2)](/developer/install/windows) - [Install on PVE](/developer/install/pve) - [Install on LXC](/developer/install/lxc) - [Install on Raspberry Pi](/developer/install/raspberry-pi) --- ### Developer Install Environment Variables (`docs/developer/install/environment-variables.md`) --- outline: [2, 3] description: Environment variables available in Olares for customizing networking, authentication, GPU support and other features. Includes configuration examples and specifications. --- # Olares environment variables Olares provides a highly customizable installation process through the use of environment variables. These variables can override default settings, enabling advanced configurations to suit your specific requirements. ## Usage examples To customize the installation process, you can set the environment variables before running the installation command. For example: ```bash # Specify Kubernetes (k8s) instead of k3s export KUBE_TYPE=k8s \ && curl -sSfL https://olares.sh | bash - ``` Or, if you have already downloaded the installation script `install.sh`: ```bash # Specify Kubernetes (k8s) instead of k3s export KUBE_TYPE=k8s && bash install.sh ``` Both methods achieve the same result. The environment variable `KUBE_TYPE` will be passed to the script, and the script will use it to modify its behavior. ## Environment variables reference The section lists all the environment variables, along with their default values, optional values, and descriptions. Configure them as needed. ### `CLOUDFLARE_ENABLE` Specifies whether to enable the Cloudflare proxy. - **Valid values**: - `0` (disable) - `1` (enable) - **Default**: `0` ### `DID_GATE_URL` Specifies the endpoint for the DID gateway. - **Valid values**: - `https://did-gate-v3.bttcdn.com` - `https://did-gate-v3.api.jointerminus.cn/` (recommended for better connectivity in mainland China) - **Default**: `https://did-gate-v3.bttcdn.com` ### `FIREBASE_PUSH_URL` Specifies the endpoint for Firebase push services. - **Valid values**: - `https://firebase-push-test.bttcdn.com/v1/api/push` - `https://firebase-push-test.api.jointerminus.cn/v1/api/push` (recommended for better connectivity in mainland China) - **Default**: `https://firebase-push-test.bttcdn.com/v1/api/push` ### `FRP_AUTH_METHOD` Sets the FRP authentication method. - **Valid values**: - `jws` - `token` (requires `FRP_AUTH_TOKEN`) - (empty) – No authentication - **Default**: `jws` ### `FRP_AUTH_TOKEN` Specifies the token for FRP communication (required if `FRP_AUTH_METHOD=token`). - **Valid values**: Any non-empty string - **Default**: None ### `FRP_ENABLE` Specifies whether to enable FRP for internal network tunneling. Requires additional FRP-related variables if using a custom server. - **Valid values**: - `0` (disable) - `1` (enable) - **Default**: `0` ### `FRP_LIST_URL` Specifies the endpoint for the Olares FRP information service. - **Valid values**: - `https://terminus-frp.snowinning.com` - `https://terminus-frp.api.jointerminus.cn` (recommended for better connectivity in mainland China) - **Default**: `https://terminus-frp.snowinning.com` ### `FRP_PORT` Specifies the FRP server's listening port. - **Valid values**: An integer in the range `1–65535` - **Default**: `7000` (if not set or set to `0`) ### `JUICEFS` Installs [JuiceFS](https://juicefs.com/) alongside Olares. - **Valid values**: `1` - **Default**: None (does not install JuiceFS if not set) ### `KUBE_TYPE` Determines the Kubernetes distribution to install. - **Valid values**: - `k8s` (full Kubernetes) - `k3s` (lightweight Kubernetes) - **Default**: `k3s` ### `LOCAL_GPU_ENABLE` Specifies whether to enable GPU support and install related drivers. - **Valid values**: - `0` (disable) - `1` (enable) - **Default**: `0` ### `LOCAL_GPU_SHARE` Specifies whether to enable GPU sharing. Applies only if GPU is enabled. - **Valid values**: - `0` (disable) - `1` (enable) - **Default**: `0` ### `MARKET_PROVIDER` Specifies the backend domain used by the application marketplace (Market). - **Valid values**: - `appstore-server-prod.bttcdn.com` - `appstore-china-server-prod.api.jointerminus.cn` (recommended for better connectivity in mainland China) - **Default**: `appstore-server-prod.bttcdn.com` ### `NVIDIA_CONTAINER_REPO_MIRROR` Specifies the APT repository mirror for installing NVIDIA Container Toolkit. - **Valid values**: - `nvidia.github.io` - `mirrors.ustc.edu.cn` (recommended for better connectivity in mainland China) - **Default**: `nvidia.github.io` ### `OLARES_SPACE_URL` Specifies the endpoint for the Olares Space service. - **Valid values**: - `https://cloud-api.bttcdn.com/` - `https://cloud-api.api.jointerminus.cn/` (recommended for better connectivity in mainland China) - **Default**: `https://cloud-api.bttcdn.com/` ### `PREINSTALL` Runs only the pre-installation phase (system dependency setup) without proceeding to the full Olares installation. - **Valid values**: `1` - **Default**: None (performs full installation if not set) ### `PUBLICLY_ACCESSIBLE` Explicitly specifies that this machine is accessible publicly on the internet, and a reverse proxy should not be used. - **Valid values**: - `0` (false) - `1` (true) - **Default**: `0` ### `REGISTRY_MIRRORS` Specifies a custom Docker registry mirror for faster image pulls. - **Valid values**: `https://mirrors.joinolares.cn` or any other valid URL - **Default**: `https://registry-1.docker.io` ### `TAILSCALE_CONTROLPLANE_URL` Specifies the endpoint for the Olares Tailscale control-plane service. - **Valid values**: - `https://controlplane.snowinning.com` - `https://controlplane.api.jointerminus.cn` (recommended for better connectivity in mainland China) - **Default**: `https://controlplane.snowinning.com` ### `TERMINUS_CERT_SERVICE_API` Specifies the endpoint for the Olares HTTPS certificate service. - **Valid values**: - `https://terminus-cert.snowinning.com` - `https://terminus-cert.api.jointerminus.cn` (recommended for better connectivity in mainland China) - **Default**: `https://terminus-cert.snowinning.com` ### `TERMINUS_DNS_SERVICE_API` Specifies the endpoint for the Olares DNS service. - **Valid values**: - `https://terminus-dnsop.snowinning.com` - `https://terminus-dnsop.api.jointerminus.cn` (recommended for better connectivity in mainland China) - **Default**: `https://terminus-dnsop.snowinning.com` ### `TERMINUS_IS_CLOUD_VERSION` Marks the machine explicitly as a cloud instance. - **Valid values**: `true` - **Default**: None ### `TERMINUS_OS_DOMAINNAME` Sets the domain name before installation to skip the interactive prompt. - **Valid values**: Any valid domain name - **Default**: None (prompts for domain name if not set) ### `TERMINUS_OS_EMAIL` Specifies the email address to use instead of a generated one. - **Valid values**: Any valid email address - **Default**: None (a temporary email is generated if not set) ### `TERMINUS_OS_PASSWORD` Specifies the password to use instead of a generated one. - **Valid values**: A valid password with 6–32 characters - **Default**: A randomly generated 8-character password ### `TERMINUS_OS_USERNAME` Specifies the username before installation to skip the interactive prompt. - **Valid values**: Any valid username (2–250 characters, excluding reserved keywords) - **Default**: None (prompts for username if not set) - **Validation**: Reserved keywords include `user`, `system`, `space`, `default`, `os`, `kubesphere`, `kube`, `kubekey`, `kubernetes`, `gpu`, `tapr`, `bfl`, `bytetrade`, `project`, `pod` ### `TOKEN_MAX_AGE` Sets the maximum validity period for a token (in seconds). - **Valid values**: Any integer (in seconds) - **Default**: `31536000` (365 days) --- ### Developer Install Install And Activate Olares (`docs/developer/install/install-and-activate-olares.md`) --- search: false --- ## Install and activate Olares :::warning Same network required To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. ::: 1. Open LarePass, on your account activation page, tap **Discover nearby Olares**. LarePass will list the detected Olares instances in the same network. 2. Select the target Olares device from the list and tap **Install now**. 3. When the installation completes, tap **Activate now**. Olares will enter the activation process, including initial configuration and network setup. 4. Follow the on-screen instructions to reset the login password for Olares, then tap **Complete**. Once activation is complete, LarePass will display the desktop address of your Olares device, such as `https://desktop.marvin123.olares.com`. {width=30%} --- ### Developer Install Installation Process (`docs/developer/install/installation-process.md`) --- outline: [2, 3] description: Technical breakdown of Olares deployment phases covering system validation, component downloads, environment preparation and service deployment. In-depth look at each installation stage. --- # Olares installation breakdown This document explains the Olares installation process from the perspective of its four main phases. It is aimed at developers and system administrators who want to understand the installation in detail, including the underlying commands, configurations, and logic behind each phase. ## Four phases of installation The Olares installation process is divided into four phases, each ensuring a smooth and stable setup: - **Precheck**: Verifies that the system environment meets all prerequisites for Olares installation. - **Download**: Retrieves all necessary files, dependencies, and container images for the installation. - **Prepare**: Configures the operating system and system services to create an environment ready for Kubernetes and Olares components. - **Install**: Deploys Kubernetes, integrates KubeSphere, and installs core Olares services and applications. ## Precheck phase The precheck phase focuses on verifying that your system meets the necessary requirements for installing Olares. The `olares-cli precheck` command is used to run a series of validation checks. Any issues identified during this phase must be resolved before continuing with the installation. Key checks include: - Checks the compatibility with the operating system type, version, and CPU architecture - Confirms that the system uses `Systemd` as its initialization process - Ensures required ports that Olares needs to expose are available - Verifies that no conflicting container runtime is installed If the precheck fails, you'll see a warning like this: In this example: - Port `9100` required by Olares is already in use. - An existing container runtime is detected in the system. You must resolve these issues before proceeding. ## Download phase The download phase retrieves the necessary wizard files, system dependencies, and container images required for Olares installation. ### Download the wizard file The wizard file is a metadata package that contains download URLs and configuration details for all Olares components. It is the first file retrieved during this phase, as it provides critical information for the subsequent downloads. By default, the wizard file is stored in: `HOME/.olares/versions/` where: - `$HOME/.olares` is the base directory for Olares. - `` refers to the version number of Olares (e.g. `1.12.0-20241215`). :::details Example script output ```bash ➜ ~ ./install.sh the KUBE_TYPE env var is not set, defaulting to "k3s" olares-cli already installed and is the expected version downloading installation wizard... current: root 2024-12-17T18:01:19.501+0800 [Job] [Download Installation Wizard] start ... 2024-12-17T18:01:19.501+0800 [Module] GreetingsModule Greetings, Olares 2024-12-17T18:01:19.502+0800 [A] ubuntu: Greetings success (611.77µs) 2024-12-17T18:01:19.502+0800 [Module] DownloadInstallWizard /home/keven/.olares/versions/v1.12.0-20241215/.env /home/keven/.olares/versions/v1.12.0-20241215/wizard/config/account/Chart.yaml ``` ::: ### Download components and container images Once the wizard file has been downloaded, the script retrieves all necessary dependencies and container images. These files are stored in: - `$HOME/.olares/pkg` for dependency packages. - `$HOME/.olares/image` for container images. This storage structure allows reusing stable components across multiple versions to avoid redundant downloads. :::details Example script output ```bash downloading installation packages... current: root 2024-12-17T19:41:36.847+0800 [Job] [Download Installation Package] start ... 2024-12-17T19:41:36.847+0800 [Module] GreetingsModule Greetings, Olares 2024-12-17T19:41:36.848+0800 [A] ubuntu: Greetings success (512.711µs) 2024-12-17T19:41:36.848+0800 [Module] GenerateOlaresUninstallScript 2024-12-17T19:41:36.879+0800 [A] LocalHost: GenerateOlaresUninstallScript success (31.279866ms) 2024-12-17T19:41:36.879+0800 [Module] PackageDownloadModule 2024-12-17T19:41:36.879+0800 checking local cache ... 2024-12-17T19:41:44.614+0800 5 out of 177 files need to be downloaded 2024-12-17T19:41:44.615+0800 (1/5) downloading package olaresd, file: olaresd-v0.0.50.tar.gz 2024-12-17T19:41:51.814+0800 (2/5) downloading image calico/kube-controllers:v3.23.2, file: 521564c4b60ae73c78899b7b40ae655e.tar.gz ... ``` ::: ## Prepare phase The prepare phase configures the system environment to support Kubernetes, container images, and Olares services. This phase involves three main tasks: - Configure the system - Set up the container runtime - Install the system daemon ### Configure system The installation script configures the Linux environment to meet Olares' requirements. These configurations include: - Adjusts DNS, NTP, and SSH services to ensure proper network functionality and time synchronization. - Installs essential dependencies (e.g., curl, net-tools, gcc, make) via `apt`. :::details Example script output ```bash preparing installation environment... current: root 2024-12-17T19:46:39.517+0800 [Job] [Prepare the System Environment] start ... 2024-12-17T19:46:39.517+0800 [Module] PreCheckOs 2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckSupport success (29.999µs) 2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckPortsBindable success (144.035µs) 2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckNoConflictingContainerd success (31.009µs) 2024-12-17T19:46:39.517+0800 [A] ubuntu: PatchAppArmor skipped (7.677µs) 2024-12-17T19:46:39.517+0800 [A] ubuntu: RaspbianCheck success (5.796µs) 2024-12-17T19:46:39.517+0800 [A] ubuntu: CorrectHostname success (5.363µs) nameserver nameserver 2024-12-17T19:46:41.921+0800 [A] ubuntu: DisableLocalDNS success (2.40336625s) 2024-12-17T19:46:41.921+0800 [INFO] installing and configuring OS dependencies ... 2024-12-17T19:46:41.921+0800 [Module] InstallDeps Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease Hit:2 https://download.docker.com/linux/ubuntu jammy InRelease Hit:3 http://hk.archive.ubuntu.com/ubuntu jammy InRelease ... ``` ::: ### Set up container runtime The container runtime is a critical component for running containerized applications. During this step, the installation script: - Installs and start the previously downloaded dependencies - Installs containerd on the system and start the service - Imports the downloaded container images into containerd :::details Example script output ```bash 2024-12-17T19:47:37.510+0800 [Module] InstallContainerModule(k3s) 2024-12-17T19:47:37.518+0800 [A] ubuntu: ZfsMountReset skipped (7.321811ms) 2024-12-17T19:47:37.525+0800 [A] ubuntu: CreateZfsMount skipped (7.322591ms) 2024-12-17T19:47:38.188+0800 [A] ubuntu: SyncContainerd success (662.643982ms) 2024-12-17T19:47:38.368+0800 [A] ubuntu: SyncCrictlBinaries success (179.758334ms) 2024-12-17T19:47:38.399+0800 [A] ubuntu: GenerateContainerdService success (31.410118ms) 2024-12-17T19:47:38.451+0800 [A] ubuntu: GenerateContainerdConfig success (52.047108ms) 2024-12-17T19:47:38.505+0800 [A] ubuntu: GenerateCrictlConfig success (53.760209ms) 2024-12-17T19:47:38.857+0800 [A] ubuntu: EnableContainerd success (352.128078ms) 2024-12-17T19:47:38.857+0800 [Module] PreloadImages 2024-12-17T19:47:41.665+0800 (1/145) imported image: rancher/mirrored-pause:3.6, time: 194.363948ms ... ``` ::: ### Install system daemon The Olares system daemon, olaresd, is then installed and started to monitor the system and automatically perform maintenance tasks. :::details Example script output ```bash 024-12-17T19:52:31.862+0800 [A] ubuntu: GenerateOlaresdEnv success (23.829684ms) 2024-12-17T19:52:31.862+0800 template OlaresdService result: [Unit] Description=olaresd After=network.target StartLimitIntervalSec=0 [Service] User=root EnvironmentFile=/etc/systemd/system/olaresd.service.env ExecStart=/usr/local/bin/olaresd RestartSec=10s LimitNOFILE=40000 Restart=always [Install] WantedBy=multi-user.target 2024-12-17T19:52:31.885+0800 [A] ubuntu: GenerateOlaresdService success (23.050958ms) 2024-12-17T19:52:32.033+0800 [A] ubuntu: EnableOlaresdService success (147.987242ms) ... ``` ::: ## Install phase The install phase brings all system components online and ensures the runtime environment is fully operational. During this phase, the script primarily completes the following tasks: - Deploy Kubernetes. - Integrate KubeSphere for cloud-native management and observability. - Configure the Olares account. - Deploy and start built-in apps and services. ### Deploy Kubernetes Kubernetes is the backbone of the Olares system. During this step, the installation script: 1. Starts the etcd database. 2. Starts and configures K3s. 3. Installs a Container Network Interface (CNI) plugin for cluster networking. 4. Copies the `kubeconfig` file to the current user's directory, enabling interaction with the cluster via `kubectl`. K3s is the default Kubernetes distribution for Olares due to its lightweight design and ease of use. However, kubernetes is also available for advanced or custom setups. On macOS, the scripts uses minikube, which will skip the above step. :::details Example script output ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ::: ### Integrate KubeSphere KubeSphere is installed on top of Kubernetes to enhance system management and observability. It provides features such as: - System monitoring and alerting. - Resource and workspace management. - Namespaces and custom resource definitions (CRDs). ### Configure account The Olares ID is created in the LarePass app. During this step, the installation script prompts you to enter the following info, so you can use LarePass to activate Olares later: - **Olares domain name**: Olares provides default names `olares.com` and `olares.cn`. This can be customized if the custom domain has been added to Olares Space. - **Olares ID**: Enter the username part of your Olares ID. This creates a system account for logging in to Olares and completes several background access and permission configurations. :::details Example script output ```bash Enter the domain name ( olares.com by default ): 2024-12-17T20:58:15.690+0800 using Domain Name: olares.com Enter the Olares ID (which you registered in the LarePass app): marvin113 2024-12-17T20:58:52.584+0800 using Olares Local Name: marvin113 2024-12-17T20:58:52.584+0800 using Olares ID: marvin113@olares.com 2024-12-17T20:58:52.584+0800 using password: 2uO5PZ2X ``` ::: ### Deploy built-in applications The final deployment step installs core services and user applications using Helm charts: - **Core system services** (in the `os-system` namespace): Includes backups (Velero), storage (OpenEBS), Redis, Nats, MinIO, etc. - **User applications** (in namespaces like `user-space-xxx`): Includes Files, Desktop, Settings, etc. During installation, the log will display messages such as `[helm] app installed success` and `xxx created`, indicating that the respective Helm charts or Kubernetes resources have been installed successfully. :::details Example script output ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ::: ### Complete the installation Once all components are deployed, the script outputs a summary with a URL for the activation wizard: ```bash 2024-12-17T21:00:58.086+0800 [INFO] Installation wizard is complete 2024-12-17T21:00:58.086+0800 [INFO] All done ------------------------------------------------ 2024-12-17T21:00:58.086+0800 Olares is running at: 2024-12-17T21:00:58.086+0800 http://192.168.1.16:30180 2024-12-17T21:00:58.086+0800 Open your browser and visit the above address 2024-12-17T21:00:58.086+0800 with the following credentials: 2024-12-17T21:00:58.086+0800 Username: marvin113 2024-12-17T21:00:58.086+0800 Password: 2uO5PZ2X ``` To complete the installation, you need to: 1. Open your browser and enter the provided URL. 2. Log in to the activation wizard with initial password. 3. Follow the on-screen prompt to finish the activation. After activation, your Olares will be fully operational and ready to use. ## Learn more - [Olares installation overview](installation-overview.md) - [Olares environment variables](environment-variables.md) --- ### Developer Install Installation Troubleshooting (`docs/developer/install/installation-troubleshooting.md`) --- search:false --- :::info Troubleshooting installation issues If any issues arise during installation, report them by [creating a GitHub issue](https://github.com/beclab/Olares/issues/new). Include the following details: - The platform or environment being used (e.g., Ubuntu, Docker, WSL, etc.). - The installation method (script or Docker image). - Detailed error information (including logs, error messages, or screenshots). ::: --- ### Developer Install Linux Via Docker Compose (`docs/developer/install/linux-via-docker-compose.md`) --- outline: [2, 3] description: Learn how to deploy Olares on a Linux server using Docker Compose. This step-by-step guide covers system requirements, configuration, installation, activation, and container management. --- # Install Olares on Linux using Docker Compose You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker, preparing the installation environment, completing the activation process, and managing the container lifecycle. :::tip Recommendation for production use For best performance and stability, we recommend [installing Olares on Linux via script](/manual/get-started/install-olares.md). ::: ## System requirements Make sure your device meets the following requirements. - CPU: At least 4 cores - RAM: At least 8GB of available memory - Storage: At least 64GB of available space (SSD recommended) - Supported systems: - Ubuntu 20.04 LTS or later - Debian 11 or later :::info Version compatibility While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). ::: ## Before you begin Before you begin, ensure the following: - [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed and running on your system. - You know the IP address of the current device. :::tip Verify host IP To verify your host IP, run the following command in the terminal: ```bash ip r ``` Look for the line starting with `default via`. It will show the default gateway and the network interface being used. ::: - You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). ## Create a new directory Create a directory to store the Olares configuration files. For example, you could make a new directory called `olares-config` with the following command: ```bash mkdir ~/olares-config cd ~/olares-config ``` ## Prepare `docker-compose.yaml` 1. Create a `docker-compose.yaml` file in the `olares-config` directory. 2. Add the appropriate content to the file based on whether GPU support is required: :::code-group <<< @/code-snippets/docker-compose.yaml <<< @/code-snippets/docker-compose-GPU.yaml ::: 3. Save the `docker-compose.yaml` file. ## Set up environment variables and start container 1. In the `olares-config` directory, use the following command to set the environment variables and start the Olares services: ```bash [With Docker Compose Plugin] VERSION= HOST_IP= docker compose up -d ``` - `VERSION=`: Specifies the Olares version. Replace `` with the actual one. For example: `1.11.5`. - `HOST_IP=`: Specifies the Linux machine's IP address. Replace `` with the actual one. After executing the command, you should see output similar to the following, showing the status and port mappings of all containers: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` 2. Verify if the container is running successfully: ```bash docker ps ``` You should see an output like this: ```bash CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 28e86c473750 beclab/olaresd:proxy-v0.1.0 "/mdns-agent" About a minute ago Up About a minute olares-olaresd-proxy-1 5fd68a8709ad beclab/olares:1.11.5 "/usr/local/bin/entr…" 2 minutes ago Up About a minute 0.0.0.0:80->80/tcp... olares-olares-1 ``` ## Manage the Olares container Ensure that you are in the directory containing the `docker-compose.yaml` file before proceeding with any commands. ### Stop the container To stop the running container: ```bash docker compose stop ``` ### Restart the container To restart the container after it has been stopped: ```bash docker compose start ``` It may take 6 to 7 minutes for all services to fully initialize after restarting. ### Uninstall the container To uninstall the container: ```bash docker compose down ``` --- ### Developer Install Log In To Olares (`docs/developer/install/log-in-to-olares.md`) --- search: false --- ## Log in to Olares 1. Enter the Olares desktop address in your browser, and press any key to continue. 2. On the login page, enter your Olares login password. 3. You will be prompted to complete the two-factor verification. You can confirm login on LarePass, or manually enter the 6-digit verification code. ::: info The verification code is time-sensitive. Ensure you enter it before it expires. If it does, you will need to generate a new code. ::: Once you've logged in, you'll be directed to the Olares desktop.🎉 --- ### Developer Install Lxc (`docs/developer/install/lxc.md`) --- description: Instructions for installing Olares on Linux Containers (LXC) including container setup, system requirements, and activation steps. --- # Install Olares on LXC LXC (Linux Containers) is a lightweight virtualization method that runs applications in isolated containers. When used on PVE, it enables an efficient way to deploy Olares without the overhead of a full virtual machine. :::warning Not recommended for production use Currently, Olares on LXC has certain limitations. We recommend using it only for development or testing purposes. ::: ## System requirements Make sure your device meets the following requirements. - CPU: At least 4 cores - RAM: At least 8GB of available memory - Storage: At least 64GB of available space (SSD recommended) - Supported systems: - PVE 8.2.2 - Linux container: Debian 12 (for existing LXC containers on PVE) :::info Version compatibility While the specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). ::: ## Prerequisites - Working directories for storing images and packages on the PVE host. You can set it using the following command: ``` bash mkdir -p /root/.olares/images /root/.olares/pkg ``` - The container template (CT) for `debian-12-standard_12.7-1_amd64.tar.zst`. Download it from the [PVE image repository](http://download.proxmox.com/images/system/). ## Configure the LXC environment ::: tip Install on existing LXC To install Olares on an existing LXC container, skip to step 2 directly. Make sure you use the corresponding container ID. ::: 1. Create the LXC container using the following script: ::: tip Unique container ID To create a container, you need to assign it a unique container ID. In this guide, we use `16553`, but you can replace it with any available numeric ID. Make sure to update all commands and configurations accordingly. ::: ``` bash{2} export ROOTPASS=123456 pct create 16553 /var/lib/vz/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \ --hostname olares \ --ostype ubuntu \ --cores 4 \ --memory 10240 \ --swap 0 \ --net0 name=eth0,bridge=vmbr0,firewall=1,ip=dhcp,ip6=dhcp,type=veth \ --rootfs local-lvm:80 \ --unprivileged 0 \ --ignore-unpack-errors \ --mp0 "/root/.olares/images,mp=/root/.olares/images" \ --mp1 "/root/.olares/pkg,mp=/root/.olares/pkg" \ --password="$ROOTPASS" ``` 2. Modify the LXC configuration. a. Open the configuration file using the following command: ``` bash nano /etc/pve/lxc/16553.conf ``` b. Copy and paste the following configurations into the file: ``` bash arch: amd64 cores: 4 hostname: olares memory: 10240 net0: name=eth0,bridge=vmbr0,firewall=1,hwaddr=BC:24:11:13:05:7C,ip=dhcp,ip6=dhcp,type=veth ostype: debian rootfs: local-lvm:vm-16553-disk-0,size=80G # Storage config mp0: /root/.olares/images,mp=/root/.olares/images mp1: /root/.olares/pkg,mp=/root/.olares/pkg # Permision config lxc.apparmor.profile: unconfined lxc.cgroup.devices.allow: a lxc.cap.drop: lxc.mount.auto: "proc sys cgroup:mixed" ``` c. Save and close the file. 3. Enable IP Virtual Server (IPVS) modules on the PVE host: ``` bash sudo modprobe ip_vs sudo modprobe ip_vs_rr sudo modprobe ip_vs_wrr sudo modprobe ip_vs_sh sudo modprobe overlay ``` 4. Start the LXC container, make initial configurations, and exit: ```bash # Start the container pct start 16553 # Enter the container pct enter 16553 # Create missing directories mkdir -p /lib/modules # Update PATH environment variable echo 'export PATH="/usr/local/bin:$PATH"' >> /root/.bashrc source ~/.bashrc # exit LXC exit ``` 5. Copy PVE dependencies to the LXC container: ``` bash # Copy kernel config from PVE host to LXC container pct push 16553 /boot/config-$(uname -r) /boot/config-$(uname -r) # Package and copy kernel modules directory tar cvf /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve pct push 16553 /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve.tar.gz # Extract the archive inside the container pct enter 16553 cd /lib/modules tar xvf /lib/modules/6.8.4-2-pve.tar.gz -C / ``` ## Install on LXC Run the following installation command inside the LXC container: --- ### Developer Install Mac Via Docker Image (`docs/developer/install/mac-via-docker-image.md`) --- outline: [2, 3] description: Learn how to run Olares as a containerized application on Mac with Docker, covering image setup and container configuration. --- # Install Olares on Mac with Docker image You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker, preparing the installation environment, completing the activation process, and managing the container lifecycle. :::warning Not for production use Currently, Olares on Mac has certain limitations including: - Lack of distributed storage support. - Inability to add local nodes. We recommend using it only for development or testing purposes. ::: ## System requirements Make sure your device meets the following requirements. - Architecture: AMD64 or ARM64 - CPU: At least 4 cores - RAM: At least 8GB of available memory - Storage: At least 64GB of available space (SSD recommended) ## Before you begin Before you begin, ensure the following: - [Docker](https://www.docker.com/) is installed and running on your system. - You know the IP address of the current device. ::: tip View IP Address To view the IP address on a Mac, there are two methods: - Using the graphical interface: Open **System Settings** (or **System Preferences**) > **Network**, and check the details under the currently active network connection. - Using the command line: Open a terminal window and enter `ipconfig getifaddr en0` for Wi-Fi, or `ipconfig getifaddr en1` for wired network. ::: - You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). ## Run `olaresd-proxy` ::: tip Check Mac chip If you are unsure which chip your Mac is using, go to the Apple menu and select **About This Mac** to verify. ::: ## Pull the Olares image To pull the image of Olares, execute the following command. Replace `` with your device's IP address and `` with the desired version of Olares: ```bash{2,9} docker run -d --privileged -v oic-data:/var \ -e HOST_IP= \ -p 80:80 \ -p 443:443 \ -p 30180:30180 \ -p 18088:18088 \ -p 41641:41641/udp \ --name oic \ beclab/olares: ``` where: - `-d`: Starts the container in detached mode to allow it to run in the background. - `--privileged`: Grants the container elevated privileges. - `-v oic-data:/var`: Binds a Docker volume (`oic-data`) to the `/var` directory inside the container to persist data. - `-e HOST_IP=`: Specifies the host device's IP address as an environment variable. - `-p 80:80`: Maps port `80` on the host to port `80` in the container. - `-p 443:443`: Maps port `443` on the host to port `443` in the container. - `-p 30180:30180`: Maps port `30180` on the host to port `30180` in the container. - `-p 18088:18088`: Maps port `18088` on the host to port `18088` in the container. - `-p 41641:41641/udp`: Maps UDP port `41641` on the host to UDP port `41641` in the container. - `--name oic`: Names the container `oic` (Olares in container) for easier reference. - `beclab/olares:`: Specifies the Olares Docker image and version. For example: `beclab/olares:1.11.5`. When the container is running, you will see a container ID output. ::: :::warning Do not add the `--rm` flag The `--rm` flag automatically deletes the container after it stops. If this happens, you will not be able to restart the container and will need to reinstall Olares to run it again. Omitting this flag preserves the container after stoppage, enabling you to resume it with the`docker start` command. ::: --- ### Developer Install Mac (`docs/developer/install/mac.md`) --- description: Step-by-step instructions for installing Olares on macOS systems including prerequisites, installation commands, and activation process. --- # Install Olares on Mac via the script This guide explains how to install Olares on macOS using the provided installation script. :::warning Not for production use Olares on Mac has certain limitations including: - Lack of distributed storage support. - Inability to add local nodes. We recommend using it only for development or testing purposes. ::: ## System compatibility Make sure your Mac meets the following requirements. - Architecture: X86-64 or ARM64 - RAM: 8 GB or above (available memory) - Storage: 90 GB or above (available disk space) - MacOS: Monterey (12) or later ## Before you begin Ensure you have the following installed: - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - [MiniKube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Farm64%2Fstable%2Fhomebrew) ::: tip It's recommended to install via `homebrew`. ::: ## Set up system environment 1. In Docker Desktop, navigate to **Settings** > **Resources**, and configure as below: - **CPU limit**: Set to at least 4 CPUs - **Memory limit**: Set to at least 9 GB - **Virtual disk limit**: Set to at least 80 GB 2. Click **Apply & restart** to implement the changes. ## Install Olares In terminal, run the following command: --- ### Developer Install Manage Olares Container (`docs/developer/install/manage-olares-container.md`) --- search: false --- ## Manage the Olares container ### Stop the container To stop the running container: ```bash docker stop oic ``` ### Restart the container To restart the container after it has been stopped: ```bash docker start oic ``` ### Uninstall the container To completely remove the container and its associated data: ```bash docker stop oic docker rm oic docker volume rm oic-data ``` --- ### Developer Install Olares Home (`docs/developer/install/olares-home.md`) --- description: Internal structure of Olares Home directory organizing images, logs, dependencies and version management. Details about the default installation directory architecture. --- # Olares Home "Olares Home" is the default installation directory for Olares. It stores images, logs, dependency components, and version management data. In this document, you will learn the structure of Olares Home and gain a clearer understanding of the Olares installation process. ## Path configuration By default, Olares Home is located at `~/.olares`. You can customize its location using the `--base-dir` option with a specific `olares-cli` command, for example: ```bash # Specifies the base directory where all downloaded components will be saved olares-cli download component --base-dir /custom/path ``` ## Directory structure A typical Olares Home directory might look like this: ``` ./olares ├── images # Stores downloaded image files │ ├── {image-file}.tar.gz │ └── {image-file}.tar.gz ├── logs # Stores all logs ├── pkg # Stores downloaded system dependency components │ ├── cni # Container Network Interface (K8s network plugins) │ ├── components # Olares foundation software dependencies (not directly related to K8s) │ │ such as olaresd, JuiceFS, Redis, etc. │ ├── containerd # Container Runtime Interface (CRI) runtime │ ├── crictl # CRI command-line tool │ ├── etcd # Persistent database for K8s │ ├── helm # Command-line tool for K8s application management │ ├── kube # Core K8s programs (e.g., kubeadm, kubelet, k3s) │ └── runc # Open Container Initiative (OCI) runtime └── versions # Stores different Olares versions ├── v1.10.0-20241001 │ ├── cli │ ├── deploy │ ├── files │ ├── images │ ├── logs # Stores logs specific to this version of Olares │ │ ├── install.log │ │ └── uninstall.log │ └── wizard # Contains Helm charts for system and user applications └── v1.10.0-20240930 ├── cli ├── deploy ├── files ├── images ├── logs │ ├── install.log │ └── uninstall.log └── wizard ``` The structure of Olares Home is designed to optimize file management, version control, and resource sharing. The advantages include: - Each Olares version is stored under the `versions` directory. All files and logs related to a particular version are contained within its subdirectory. - Only one Olares instance can run on a single machine at a time, preventing version conflicts. - The `images` and `pkg` directories are shared across all Olares versions. This design reduces redundancy, minimizes duplicate downloads, and saves disk space. ## Learn more - [Olares CLI](../install/cli-1.11/olares-cli.md) - [Olares installation breakdown](installation-process.md) - [Olares environment variables](environment-variables.md) --- ### Developer Install Pve (`docs/developer/install/pve.md`) --- description: Guide to installing Olares on Proxmox VE (PVE) with system requirements, installation commands, and step-by-step activation instructions. --- # Install Olares on PVE Proxmox Virtual Environment (PVE) is an open-source virtualization platform based on Debian Linux. This guide explains how to install Olares in a PVE environment. :::warning Not recommended for production use Currently, Olares on PVE has certain limitations. We recommend using it only for development or testing purposes. ::: ## System requirements Make sure your device meets the following requirements. - CPU: At least 4 cores - RAM: At least 8GB of available memory - Storage: At least 64GB of available space (SSD recommended) - Supported Systems: PVE 8.2.2 :::info Version compatibility While the specific version is confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). ::: ## Install on PVE In PVE CLI, run the following command: --- ### Developer Install Raspberry Pi (`docs/developer/install/raspberry-pi.md`) --- description: Complete guide to installing Olares on Raspberry Pi including hardware requirements, installation process, and system activation steps. --- # Install Olares on Raspberry Pi This guide explains how to install Olares on a Raspberry Pi. :::warning Not recommended for production use Currently, Olares on Raspberry Pi has certain limitations. We recommend using it only for development or testing purposes. ::: ## System requirements Make sure your Raspbian device meets the following requirements. - Hardware: Raspberry Pi 4B or Raspberry Pi 5 with 8GB memory - Operating system: Raspbian 12 - Storage: 64GB (SSD recommended) ## Set up system environment 1. Configure the Raspbian environment to enable necessary features: ```bash echo "$(head -1 /boot/firmware/cmdline.txt) cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1" | sudo tee /boot/firmware/cmdline.txt echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt ``` 2. Reboot your Raspbian device to apply the change. ```bash sudo reboot ``` ## Install Olares Run the following command: --- ### Developer Install Reusables (`docs/developer/install/reusables.md`) --- search: false --- ```bash curl -fsSL https://olares.sh | bash - ``` :::tip Root user password During the installation, you may be prompted to enter your root password. ::: :::info Errors during installation? If an error occurs during installation, use the following command to uninstall first: ```bash bash olares-uninstall.sh ``` After uninstalling, retry the installation by running the original installation command. ::: ## Prepare Wizard URL At the end of the installation process, you will be prompted to enter your domain name and Olares ID. For example, if your full Olares ID is `alice123@olares.com`: - **Domain name**: Press `Enter` to use the default domain name or type `olares.com`. - **Olares ID**: Enter the prefix of your Olares ID. In this example, enter `alice123`. Upon completion of the installation, the initial system information, including the Wizard URL and the initial login password, will appear on the screen. You will need them later in the activation stage. ## Next step: Protect your Olares ID You're almost ready to start using Olares! Before diving in, it's crucial to ensure your Olares ID is securely backed up. Without this step, you won't be able to recover Olares ID if needed. - [Back up your mnemonic phrase](/manual/larepass/back-up-mnemonics.md) :::info Having trouble with installation? If you encounter issues during the installation process, feel free to [submit a GitHub Issue](https://github.com/beclab/Olares/issues/new). Please include the following information when submitting: - The platform or environment you're using (e.g., Ubuntu, Docker, WSL, etc.). - The installation method (script installation or Docker image). - Detailed error information (including logs, error messages, or screenshots). ::: --- ### Developer Install Versioning (`docs/developer/install/versioning.md`) --- outline: [2, 3] description: Version management system in Olares covering release types, branch strategies and upgrade specifications. Details about semantic versioning implementation and compatibility. --- # Olares versioning The Olares versioning and release process is designed to provide clear version definitions and stable upgrade paths. This document outlines Olares' versioning rules, release types, branch management practices, and upgrade guidelines. ## Versioning rules Olares primarily follows the [Semantic versioning specification](https://semver.org/), which defines versions in format `Major.Minor.Patch[-PreReleaseVersion]`. For example, `1.11.0-rc.0` represents a release candidate for version `1.11.0`. Versions are ordered as follows: `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` < `1.0.0` ## Release types Olares offers three types of releases: **Stable**, **Release Candidate (RC)**, and **Daily build**. ### Stable releases Stable releases are thoroughly tested versions suitable for production environments. The official one-line installation command always defaults to the latest stable version. - **Release cadence**: Monthly - **Examples**: `v1.10.5`, `v1.11.0`, `v1.11.1`, `v1.12.0` ### Release Candidate (RC) releases RC releases are pre-release versions for testing before a stable release. RC releases may go through several iterations before being promoted to stable. - **Release cadence**: Based on testing status - **Examples**: `v1.11.0.rc.0`, `v1.11.0.rc.1` ### Daily build releases Daily build releases, or daily builds are automatically generated from the `main` branch every day at 2:00 AM (UTC+8), with the build date embedded in the version name. These versions reflect the latest code changes and are intended for development and testing purposes. Daily builds are often unstable and not suitable for production use. - **Release cadence**: Daily - **Examples**: `v1.12.0-20241201` ## Release branch management During the `1.x` phase, Olares follows a structured monthly release cadence: 1. At the end of each month, a release branch (e.g., `release-1.11`) is created from the `main` branch. 2. An initial RC version (e.g., `v1.11.0.rc.0`) is released from the new release branch. Additional RC versions may follow as testing progresses. 3. The `main` branch transitions to the next version (e.g., from `v1.11` to `v1.12`). 4. Issues identified in the stable version are addressed through patch releases (e.g., `v1.11.1`), based on the corresponding release branch. Developers can submit pull requests (PRs) to both the `main` branch and the relevant release branch as needed. ## Upgrade policies and compatibility Olares is in a rapid development phase with frequent feature additions and changes. To ensure stability and avoid unexpected issues, Olares follows a controlled upgrade policy: - **Upgrades within the same minor version**: Upgrading within the same minor version (e.g., `1.4.0` to `1.4.2`) is fully supported. These updates typically include bug fixes or small improvements that do not affect compatibility. - **Upgrades across minor versions**: Upgrading from one minor version to another (e.g., `1.4.x` to `1.5.x`) involves more significant changes, such as new features or architectural updates. Because these changes may not be backward-compatible, automatic upgrades are **not supported**. Instead, users must manually uninstall the existing version before installing the newer version. The type of release you are using also determines what upgrades are possible: - **Stable**: You can only upgrade to newer stable releases, ensuring maximum reliability and stability. - **RC**: You can upgrade to newer RC versions or stable releases as they become available. - **Daily build**: You can upgrade to newer daily build, RC, or stable releases. ::: tip Future upgrade policy In the next major release, Olares plans to fully support seamless automatic upgrades for all versions within the same major version. ::: --- ### Developer Install Windows Via Docker Image (`docs/developer/install/windows-via-docker-image.md`) --- outline: [2, 3] description: Learn how to run Olares on Windows using WSL 2 and Docker, including system preparation, configuration, and container management. --- # Install Olares on Windows (WSL 2) with Docker image You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker and WSL 2, preparing the installation environment, completing the activation process, and managing the container lifecycle. :::warning Not recommended for production use Currently, Olares on Windows has certain limitations including: - Lack of distributed storage support - Inability to add local nodes. We recommend using it only for development or testing purposes. ::: ## System requirements Make sure your Windows meets the following requirements. - CPU: At least 4 cores - RAM: At least 16GB of available memory - Storage: At least 64GB of available space (SSD recommended) - Supported systems: - Windows 10 or 11 - Linux (on WSL 2): Ubuntu 20.04 LTS or later; Debian 11 or later ## Before you begin Before you begin, ensure the following: - [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) is installed and running on your system. :::info WSL 2 and Hyper-V If Docker Desktop is configured to use **Hyper-V**, GPU support for Olares cannot be enabled. Ensure Docker Desktop is set to run in the **WSL 2** mode. ::: - You know the IP address of the current device. ::: tip View IP Address In PowerShell or Command Prompt, use the following command to confirm your IP address: ```bash ipconfig | findstr /i "IPv4.*192" ``` ::: - You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). ## Configure WSL 2 1. Open PowerShell and run the following command to confirm the kernel version of WSL installed on your system: ```powershell wsl --version ``` Example output: ```PowerShell{2} WSL version: 2.4.8.0 Kernel version: 5.15.167.4-1 WSLg version: 1.0.65 MSRDC version: 1.611.1-81528511 DXCore version: 10.0.26100.1-240331-1435.ge-release Windows version: 10.0.26100.3475 ``` 2. Use the link provided to download the appropriate kernel file matching your version: `https://dc3p1870nn3cj.cloudfront.net/bzImage-`. For example, For kernel version `5.15.167.4`, download the file from `https://dc3p1870nn3cj.cloudfront.net/bzImage-5.15.167.4`. Supported kernel versions (above `5.15.146.1`) are: - `linux-msft-wsl-5.15.146.1` - `linux-msft-wsl-5.15.150.1` - `linux-msft-wsl-5.15.153.1` - `linux-msft-wsl-5.15.167.4` - `linux-msft-wsl-6.6.75.1` - `linux-msft-wsl-6.6.36.6` - `linux-msft-wsl-6.6.36.3` 3. Set the default version of WSL to version 2: ```bash wsl --set-default-version 2 ``` 4. In the directory `C:\Users\\`, create a file named `.wslconfig` with the following content: ```txt [wsl2] kernel=c:\\path\\to\\your\\kernel\\bzImage- # Note: Use double backslashes (\\) as path separators memory=8GB # Recommended: 16GB swap=0GB ``` :::info If you installed Docker Desktop before modifying the `.wslconfig` file, it is recommended to remove the `docker-desktop` distribution installed under WSL: ```bash wsl --unregister docker-desktop wsl --unregister docker-desktop-data # If this version exists ``` ::: 5. Restart your computer to apply the changes. ## Prepare Docker If you have installed Docker Desktop before modifying `.wslconfig`, remove docker desktop then restart Windows. ## Run `olaresd-proxy` 1. Download `olaresd-proxy`from the following link: `https://dc3p1870nn3cj.cloudfront.net/olaresd-proxy-v0.1.0-windows-amd64.tar.gz`. 2. Extract the file and start the `olaresd-proxy` executable. :::info Keep `olaresd-proxy` running Ensure that `olaresd-proxy` runs in the background during the installation and activation of Olares. ::: ## Run Olares using the Docker CLI :::warning CUDA version requirements CUDA version 12.4 or above is required for GPU support. Older versions are incompatible. ::: Run the following command to pull the Olares image. Replace `` with your device's IP address and `` with the desired version of Olares: ::: code-group ```bash{2,9} [Without GPU support] docker run -d --privileged -v oic-data:/var \ -e HOST_IP= \ -p 80:80 \ -p 443:443 \ -p 30180:30180 \ -p 18088:18088 \ -p 41641:41641/udp \ --name oic \ beclab/olares: ``` ```bash{1,2,9} [With GPU support] docker run --gpus all -d --privileged -v oic-data:/var \ -e HOST_IP= \ -p 80:80 \ -p 443:443 \ -p 30180:30180 \ -p 18088:18088 \ -p 41641:41641/udp \ --name oic \ beclab/olares: ``` ::: where: - `-d`: Starts the container in detached mode to allow it to run in the background. - `--privileged`: Grants the container elevated privileges. - `-v oic-data:/var`: Binds a Docker volume (`oic-data`) to the `/var` directory inside the container to persist data. - `-e HOST_IP=`: Specifies the host device's IP address as an environment variable. - `-p 80:80`: Maps port `80` on the host to port `80` in the container. - `-p 443:443`: Maps port `443` on the host to port `443` in the container. - `-p 30180:30180`: Maps port `30180` on the host to port `30180` in the container. - `-p 18088:18088`: Maps port `18088` on the host to port `18088` in the container. - `-p 41641:41641/udp`: Maps UDP port `41641` on the host to UDP port `41641` in the container. - `--name oic`: Names the container `oic` (Olares in container) for easier reference. - `beclab/olares:`: Specifies the Olares Docker image and version. For example: `beclab/olares:1.11.5`. When the container is running, you will see a container ID output. :::warning Do not add the `--rm` flag The `--rm` flag automatically deletes the container after it stops. If this happens, you will not be able to restart the container and will need to reinstall Olares to run it again. Omitting this flag preserves the container after stoppage, enabling you to resume it with the`docker start` command. ::: --- ### Developer Install Windows (`docs/developer/install/windows.md`) --- outline: [2, 3] description: Guide to installing Olares on Windows using WSL (Windows Subsystem for Linux) including setup requirements and activation steps. --- # Install Olares on Windows via the script This guide explains how to install Olares on Windows (WSL 2) using the provided installation script. :::warning Not recommended for production use Currently, Olares on Windows has certain limitations including: - Lack of distributed storage support - Inability to add local nodes. We recommend using it only for development or testing purposes. ::: ## System compatibility Make sure your Windows meets the following requirements. - CPU: At least 4 cores - RAM: At least 16GB of available memory - Storage: At least 64GB of available space (SSD recommended) - Supported systems: - Windows 10 or 11 - Linux (on WSL 2): Ubuntu 20.04 LTS or later; Debian 11 or later ## Set up system environment 1. Enable the required Windows features for virtualization. a. Open **Control Panel**, then go to **Programs** > **Programs and Features** > **Turn Windows features on or off**. b. In the **Windows Features** window, check: - **Hyper-V** (not required for Windows 10 Home and Windows 11 Home) - **Windows Subsystem for Linux** - **Virtual Machine Platform** c. Click **OK** and restart your computer when prompted. 2. Set the execution policy for the current user. a. Open PowerShell as administrator, then run the following command: ```powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser ``` b. When prompted to check whether to change the execution policy, type `A` and press **Enter** to confirm. ```powershell{5} Execution Policy Change The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose you to the security risks described in the about_Execution_Policies help topic at https:/go.microsoft.com/fwlink/?LinkID-135170. Do you want to change the execution policy? [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): ``` ## Install Olares 1. Click https://windows.olares.sh to download the installation script `publicInstall.latest.ps1`. 2. Execute the script. a. Open PowerShell as administrator, then navigate to the folder where the script is located. For example, if the script is in the `Downloads` folder, run the following command: ```powershell cd C:\Users\\Downloads ``` b. Once in the correct folder, run the following command: ```powershell .\publicInstall.latest.ps1 ``` :::warning Administrator privileges required Running PowerShell without administrator privileges will cause the installation to fail. See [How to make sure I am using PowerShell as administrator](#how-to-make-sure-i-am-using-powershell-as-administrator). ::: 3. When prompted with security warning, type `R` and press **Enter** to run the script once. The installation process for Olares will start. ```powershell{4} Security warning Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run publicInstall.latest.ps1? [D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"): ``` 4. When prompted to select the drive to store the WSL Ubuntu distro, type the drive letter of an available disk. Ensure the selected drive has at least **80 GB** of free space. ```powershell{8} Installing Olares will create a WSL Ubuntu Distro and occupy at least 80 GB of disk space. Please select the drive where you want to install it. Available drives and free space: C:\ Free Disk: 391.07 GB D:\ Free Disk: 281.32 GB Please enter the drive letter (e.g., C): ``` 5. When prompted with the firewall rules setup, type `yes` to automatically configure them, or type `no` to skip this step.
If you choose to skip, either [disable Windows Firewall Defender](#how-to-disable-windows-defender-firewall), or [manually add TCP inbound rules](#how-to-manually-set-firewall-rules). ```powershell{2} Accessing Olares requires setting up firewall rules, specifically adding TCP inbound rules for ports 80, 443, and 30180. Do you want to set up the firewall rules? (yes/no): ``` 6. When promoted to confirm the IP address of Windows, type **Y** to confirm, or **R** to re-enter. ```powershell The NAT gateway (the Windows host)'s IP is 192.168.50.136. Confirm [Y] or Re-enter [R]? ``` ::: tip Obtain the IPv4 address of Windows You can get the IPv4 address in advance by running `ipconfig` in the Windows command line. ::: :::info Errors during installation? If an error occurs during installation, use the following command to uninstall first: ```powershell wsl --unregister ubuntu ``` After uninstalling, retry the installation by running the original installation command. ::: ## FAQ ### How to make sure I am using PowerShell as administrator? You can confirm that PowerShell is running as an administrator if you see "Administrator: Windows PowerShell" in the title bar of the PowerShell window. {width=70%} If not, use one of the following methods: - Search for "PowerShell" in the **Start** menu, right-click it, and select **Run as administrator**. - Or press **Win** + **R**, type `powershell`, and press **Ctrl** + **Shift** + **Enter** to open PowerShell as an administrator. ### How to configure the CPU and memory for WLS? When installing Olares in WSL, the default memory allocation is `12GB`. But you can configure the memory before Olares installation, or adjust both memory and CPU settings after installation. **Adjust the memory setting before installation** For example, to allocate 16GB of memory: 1. Add a user variable with the following: - **Variable name**: `WSL_MEMORY` - **Variable value**: `16` 2. Click **OK** to apply changes. :::tip If you already have a PowerShell window open, changes to environment variables will not take effect in the current session. To ensure the updated environment variables are loaded, open a new PowerShell terminal as administrator, and then run the installation script. ::: **Adjust memory and CPU settings after installation** After installation, a configuration file named `.wslconfig` will be created in the current user's home directory (`C:\Users\\`). This file allows you to adjust memory and CPU settings. The default configuration looks like this: ```bash [wsl2] memory=12GB swap=0GB ``` For example, to use 4 CPU cores: 1. Add the `processors` parameter to the file: ```bash [wsl2] memory=12GB processors=4 swap=0GB ``` 2. Save the `.wslconfig` file with your custom changes. 3. Close all running virtual machines by running the following command in PowerShell: ```powershell wsl --shutdown ``` 4. Restart Olares by running: ```powershell wsl -d Ubuntu ``` It will take a few minutes for Olares services to restart. ### How to reactivate Olares after the PC restarts? Run the following command in PowerShell to restart the Olares service: ```powershell wsl -d Ubuntu ``` ### How to disable Windows Defender Firewall? :::tip You can turn on Windows Defender Firewall when the Olares installation completes. ::: To completely disable the firewall: 1. Open **Control Panel** > **System and Security** > **Windows Defender Firewall**. 2. In the navigation pane, click **Turn Windows Defender Firewall on or off**. 3. Select **Turn off Windows Defender Firewall** for both private and public networks, then click **OK**. ### How to manually set firewall rules? If you choose not to configure firewall rules during installation, follow these steps to set them manually: 1. Open **Control Panel** > **System and Security** > **Windows Defender Firewall**. 2. In the navigation pane, select **Advanced settings**. 3. In the navigation pane, right-click **Inbound Rules** and select **New Rule**. 4. In the **New Inbound Rule Wizard**, select **Port** and click **Next**. 5. In **Specific local ports**, enter `80`, `443`, `30180`, and click **Next**. 6. Select **Allow the connection** and click **Next**. 7. Confirm the rules apply to **Domain**, **Private**, and **Public**, then click **Next**. 8. Provide a name for the rule and click **Finish**. ### How to uninstall Olares? Run the following command in PowerShell: ```powershell wsl --unregister ubuntu ``` --- ### Manual Best Practices Install Olares Multi Node (`docs/manual/best-practices/install-olares-multi-node.md`) --- outline: [2, 3] description: Technical guide for installing and configuring a multi-node Olares cluster. Learn how to set up master nodes with JuiceFS support, add worker nodes, and handle network changes in your cluster environment. --- # Install a multi-node Olares cluster The default Olares installation sets up a single-node cluster. Starting from v1.11.3, Olares supports adding worker nodes. This tutorial explains how to configure a master node and add worker nodes to create a scalable, multi-node Olares cluster. :::warning Alpha feature This feature is currently in the **Alpha** stage and is not recommended for production environments. It may contain performance issues and require additional manual configurations. If you encounter any issues, please report them to the [Olares GitHub repository](https://github.com/beclab/Olares/issues). ::: :::info Linux-only support This feature is currently only available for Linux systems. ::: ## Objectives In this tutorial, you will learn how to: - Install Olares on the master node with support for JuiceFS. - Add a worker node to the cluster. - Handle potential network changes to ensure the cluster continues to function properly and efficiently. ## Before you begin Before you begin, make sure the following requirements are met: - Prior experience with Kubernetes and system administration. - Both master and worker nodes must be on the same local network. - Master and worker nodes must have unique hostnames to avoid conflicts. - The worker node must be able to connect to the master node via SSH. This means: - For the root user or a user with `sudo` privileges: add the worker node's SSH public key to the master node's `authorized_keys` file. - For non-root user: enable password-based SSH authentication on the master node. ## Step 1: Set up the master node ::: tip Uninstall existing Olares cluster If you have already installed an Olares cluster using the default installation command, uninstall it using `bash olares-uninstall.sh` before you set up your master node. ::: To set up the master node with the JuiceFS support, run the following command: ```bash export JUICEFS = 1 \ && curl -sSfL https://olares.sh | bash - ``` This command installs Olares with a built-in MinIO instance as the backend storage. The installation process is identical to a single-node one and will prompt you to enter the domain name, and provide username of your Olares ID. :::tip Custom storage If you already have your own MinIO cluster or an S3 (or S3-compatible) bucket, you can configure Olares to use it instead of the built-in MinIO instance. ::: ## Step 2: Add a worker node to the cluster 1. On the worker node, download `joincluster.sh` from https://joincluster.com. 2. Run the `joincluster.sh` script with the necessary environment variables. These variables tell the worker node how to connect to the master node. At a minimum, you must set the MASTER_HOST variable, which specifies the IP address of the master node: ```bash export MASTER_HOST=192.168.1.15 ./joincluster.sh ``` Below is a list of the variables you might need to set: | **Variable** | **Description** | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MASTER_HOST` | The IP address of the master node.
Required. | | `MASTER_NODE_NAME` | The Kubernetes node name of the master node.
If not specified, the script will prompt you interactively to confirm the required parameter.
Optional. | | `MASTER_SSH_USER` | The username to log in to the master node via SSH.
By default, this is root. | | `MASTER_SSH_PASSWORD` | The password for the SSH user.
This is required if you're not using SSH keys. | | `MASTER_SSH_PRIVATE_KEY_PATH` | The path to the private SSH key for authentication.
If not specified, the script will prompt you interactively to confirm the required parameter.
Defaults to `/root/.ssh/id_rsa`. | | `MASTER_SSH_PORT` | The port number for the SSH service on the master node.
Defaults to `22`. | :::info - Non-root users must provide a password to execute commands with `sudo`. Therefore, using a non-root `MASTER_SSH_USER` without specifying `MASTER_SSH_PASSWORD` is not allowed. - Environment variables set with `export` will remain active in your current terminal session. Be careful to clear (`unset`) any conflicting variables when switching between different setups. `bash unset MASTER_SSH_PRIVATE_KEY_PATH ` ::: ## Examples Here are practical examples to help you understand how to run the `joincluster.sh` script under different scenarios. ### Example 1: Default setup If the master node IP is `192.168.1.15`, the default user is `root`, the port is `22`, and the master node's `/root/.ssh/authorized_keys` already contains the public key `/root/.ssh/id_rsa.pub` from the current node, run: ```bash export MASTER_HOST=192.168.1.15 ./joincluster.sh ``` ### Example 2: Custom SSH key path If the master node IP is `192.168.1.15`, with SSH port `22` and SSH user `root`, and the worker node uses a custom SSH key located at `/home/olares/.ssh/id_rsa`, run: ```bash export MASTER_HOST=192.168.1.15 \ MASTER_SSH_PRIVATE_KEY_PATH=/home/olares/.ssh/id_rsa ./joincluster.sh ``` ### Example 3: Non-root user with password If the master node is at `192.168.1.15`, with SSH port `22`, and the SSH user is `olares` (a sudo-privileged user) with the password `olares`, run: ```bash export MASTER_HOST=192.168.1.15 \ MASTER_SSH_USER=olares \ MASTER_SSH_PASSWORD=olares ./joincluster.sh ``` ## Uninstall a worker node On the worker node, run the following: ```bash olares-cli olares uninstall ``` ## Handle network changes Once your cluster is set up, changes in network configurations can disrupt the master-worker communication. ### If the network of master node changes - **If the master node moves to a different LAN**: The Olares system daemon (olaresd) will detect this and trigger a `changeip` event with `olares-cli`. The master node will continue working, but worker nodes will lose communication with it and stop functioning. - **If the master node's IP changes within the same LAN**: The worker nodes will still lose communication because they cannot detect the new IP automatically. To resolve this, use the `olares-cli` command on the worker nodes to update the master node's IP address and restart the dependent services: ```bash sudo olares-cli olares change-ip -b /home/olares/.olares --new-master-host 192.168.1.18 ``` where: - `-b /home/olares/.olares`: Specifies the base directory for Olares (default: `$HOME/.olares`). - `--new-master-host 192.168.1.18`: Specifies the new IP address of the master node. ### If the network of worker node changes - **If a worker node moves to a different LAN**: The worker node will lose communication with the master node and stop functioning. - **If the worker node's IP changes within the same LAN**: olaresd will automatically report the new IP to the master node, and no manual intervention is required. ## Learn more - [Olares system architecture](../system-architecture.md#distributed-file-system): Understand the distributed file system that underpins Olares, ensuring scalability, high availability, and seamless data management. - [The system daemon: olaresd](../../developer/install/installation-overview.md#system-daemon-olaresd): Learn about the central system process that orchestrates and manages core Olares functions. - [Data](../concepts/data.md#juicefs): Dive into how Olares leverages JuiceFS to provide a unified file system for efficient data storage and retrieval. - [Olares CLI](../../developer/install/cli-1.11/olares-cli.md): Explore the command-line interface for managing Olares installation. - [Olares environment variables](../../developer/install/environment-variables.md): Learn about the environment variables that enable advanced configurations of Olares. - [Install Olares](../get-started/install-olares.md): Understand how to install and activate Olares. --- ### Manual Best Practices Organize Content (`docs/manual/best-practices/organize-content.md`) --- outline: [2, 3] description: Complete guide to building your knowledge hub with Wise in Olares. Learn how to collect web content, manage PDFs and e-books, subscribe to RSS feeds, and organize your digital content library effectively. --- # Build your knowledge hub with Wise Managing information across different sources and devices can be a challenge. You might find yourself using multiple tools to bookmark articles, track RSS feeds, or manage documents, only to end up with fragmented workflows. Wise, a built-in app in Olares, is designed to centralize and organize your knowledge. It collects information from the web and your devices, using local recommendation algorithms to help you discover meaningful content privately and free from algorithmic bias. This tutorial guides you on how to leverage Wise and LarePass to collect, organize, and access content across platforms. ## Objectives By the end of this tutorial, you will learn how to: - Use LarePass Chrome browser extension or mobile client to collect content directly from the web while you browse. - Organize your existing files, such as PDFs and EPUBs, by uploading them into Wise. - Stay up-to-date with your favorite blogs, podcasts, or video playlists by subscribing to RSS feeds. - Quickly locate and retrieve any piece of content from your curated information hub. ## Before you begin Before you begin, make sure that: - Your Olares device is activated and actively running. - Your Olares ID is [secured with mnemonic phrases](/manual/larepass/back-up-mnemonics.md). - The LarePass app is installed on your phone. ## Install the LarePass browser extension The LarePass browser extension is the core tool for content discovery and collection. ::: tip Support for Chrome only The LarePass extension is currently only available for Chrome. ::: :::tip Quick access After installation, pin the LarePass extension in Chrome extension menu for quick and easy access. ::: Once logged in, your LarePass browser extension and your Olares device are synced. This means that any content you collect via LarePass extension will automatically be added to your Wise library. ## Collect web content You can collect online content, including web articles, videos, podcasts, using the LarePass browser extension, or the mobile client. ### Collect via the LarePass extension ::: tip Uploading cookies for better experience Some websites restrict access for anonymous users. In such cases, you can upload your cookies to Olares for better experience. 1. Log into the website, open the LarePass extension. 2. Go to **Collect** > **Cookie**, and click **Upload**. You can hover over cookies to view details. If you don't want to upload a specific cookie item, click **X** to unselect it. ::: To collect web content using the LarePass extension: 1. Open the content page, for example, a CNN article. 2. Open the LarePass extension. The extension will automatically detect the collectable content on the page. 3. In **Collect** > **Page**, click add_box next to the title to add the page to the Wise library. Once collected, you can find the content in **Library** > **Articles** in Wise. All media files, including audios, videos, and images on the page, will also be downloaded locally to the `/download/Wise/Article` directory. ### Collect via the LarePass mobile client You can share web links to the LarePass mobile client for content collection. :::info The exact steps may vary depending on your operating system and browser. The following uses Safari as an example. ::: 1. Tap **ios_shareShare** in the browser, then either: - Select the LarePass icon in the sharing options, or - Tap **LarePass** in **Other Actions** You will be redirected to the LarePass app. LarePass will automatically detect the collectable content on the shared page and prompt whether to add it to Wise. 2. Tap **Confirm** to add it to the Wise library. ::: tip Copy URL to share Alternatively, you can copy the URL directly and open LarePass. LarePass will automatically detect the URL in the clipboard and the collectable content as well. ::: Once added, you can find the content in **Library** > **Articles** in Wise. ## Upload PDF/E-book content to Wise You can upload local PDF or EPUB e-books to Wise for centralized knowledge management. This allows you to keep your reading materials, notes, and related content in one place, making it easier to organize, search, and reference them whenever needed. 1. Open **Wise**, click add_circle in the menu bar, and select **Upload**. 2. Navigate to the directory that contains the file you wish to upload, select the file, and click **Confirm**. View your PDFs under **Library** > **PDFs** and EPUBs under **Library** > **Books**. ::: tip You can efficiently categorize and connect related content instantly with tags, or capture insights and ideas directly alongside the content using notes. For details, refer to [Organize your reading](../olares/wise/basics.md#organize-your-reading). ::: ## Subscribe to RSS feeds You can subscribe to podcasts, blogs, and your video playlists in Wise. New episodes or updates are automatically downloaded, ensuring you stay up-to-date without worrying about content being deleted or becoming inaccessible. Additionally, Wise can automatically download your favorite videos from platforms like YouTube, even for sources that aren't RSS-supported natively. ### Subscribe via the LarePass extension To subscribe an RSS feed using the LarePass extension: 1. Open the RSS page you want to subscribe to, for example, the "Paranormal Mysteries" podcast: `https://www.spreaker.com/podcast/paranormal-mysteries--2321086`. 2. Open the LarePass extension. It will automatically detect the RSS source on the page and show the **RSS** tab. 3. In the **RSS** tab, find the correct subscription source and click bookmark_add to subscribe. ### Manually add an RSS source To manually add an RSS source to Wise: 1. Copy the RSS subscription link, such as [https://hnrss.org/frontpage](https://hnrss.org/frontpage), an RSS feed for HackerNews frontliners. 2. In Wise, click add_circle in the menu bar, and select **RSS feed**. 3. Paste the URL. Wise will automatically detect the available RSS source. {width=50%} 4. Click **Add** to subscribe. ### Automatically download videos In addition to regular RSS subscriptions, you can use the LarePass extension and Wise to automatically download videos from your playlist on video platforms. Here's how to do it on YouTube: 1. Log into your YouTube account. 2. In LarePass extension, go to **Collect** > **Cookie**, and click **Upload** to upload the cookies to Olares. Olares needs the cookies of the site to access your subscription and download videos. ::: tip Enable Auto-Sync Cookie data may expire. It is recommended that you enable the **Auto-Sync** feature in the Cookies page to ensure your cookies are updated automatically each time you visit the site. ::: 3. Under the video you want to watch, click more_horiz, select **Save**, and then click **Create New Playlist**. For example, `Save to Wise`. 4. Enter your playlist. The LarePass extension will automatically detect the available RSS feeds and show the **RSS** tab. 5. In the **RSS** tab, select the RSS feed with a link starting with `https://www.youtube.com/feeds/...` and click bookmark_add to subscribe. Wise will automatically download all the videos saved to this playlist. ::: tip Download videos from a specific channel You can use LarePass extension similarly on your favorite YouTuber's channel. Once you get the corresponding RSS feed and subscribe to it, Wise will automatically download all the videos in the channel. ::: ### Access your RSS content To access your RSS content in Wise: 1. From the left-hand menu bar, navigate to **Subscriptions** > **Feeds**. 2. Select an unread RSS item and enter it to watch the video, listen to the podcast, or simply read the article. ::: tip Smart content recommendations In addition to regular RSS subscriptions, Wise offers a fully local, privacy-protected intelligent content recommendation system. You can download the recommended algorithms from the Olares app market. Learn more in [Discover themed content](../olares/wise/recommend.md). ::: ## Search through collected content ## Learn more - [Wise basics](../olares/wise/basics.md) - [Discover themed content](../olares/wise/recommend.md) - [Subscribe and manage feeds](../olares/wise/subscribe.md) --- --- METRICS --- - Files Extracted: 96 - Estimated Token Budget: ~74607 tokens - Canonical Reference: https://codewiki.google/github.com/beclab/docs