Olares

English

简体中文

English

简体中文

Appearance

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 olares 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:

Precheck

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/<version>

where:

  • $HOME/.olares is the base directory for Olares.
  • <version> refers to the version number of Olares (e.g. 1.12.0-20241215).
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.

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.
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
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.

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.

Example script output
bash
[certs] Generating "ca" certificate and key
[certs] admin-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16]
[certs] member-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16]
[certs] node-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16]
2024-12-17T19:52:36.957+0800        [A] LocalHost: GenerateETCDCerts success (263.237575ms)
2024-12-17T19:52:37.263+0800        [A] ubuntu: SyncCertsFile success (306.213676ms)
2024-12-17T19:52:37.264+0800        [A] ubuntu: SyncCertsFileToMaster skipped (20.351µs)
2024-12-17T19:52:37.264+0800        [Module] InstallETCDBinaryModule
2024-12-17T19:52:37.698+0800        [A] ubuntu: InstallETCDBinary success (434.014395ms)
2024-12-17T19:52:37.728+0800        [A] ubuntu: GenerateETCDService success (30.732882ms)
2024-12-17T19:52:37.728+0800        [A] ubuntu: GenerateAccessAddress success (23.491µs)
2024-12-17T19:52:37.728+0800        [Module] ETCDConfigureModule
2024-12-17T19:52:37.728+0800        [A] ubuntu: ExistETCDHealthCheck skipped (9.903µs)
2024-12-17T19:52:37.753+0800        [A] ubuntu: GenerateETCDConfig success (24.125665ms)
2024-12-17T19:52:37.773+0800        [A] ubuntu: AllRefreshETCDConfig success (20.321235ms)
2024-12-17T19:52:40.048+0800        [A] ubuntu: RestartETCD success (2.274541565s)
2024-12-17T19:52:40.068+0800        [A] ubuntu: AllETCDNodeHealthCheck success (20.251062ms)
2024-12-17T19:52:40.094+0800        [A] ubuntu: RefreshETCDConfigToExist success (26.207599ms)
2024-12-17T19:52:40.129+0800        [A] ubuntu: AllETCDNodeHealthCheck success (34.462881ms)
2024-12-17T19:52:40.129+0800        [Module] ETCDBackupModule
2024-12-17T19:52:40.185+0800        [A] ubuntu: BackupETCD success (56.639923ms)
2024-12-17T19:52:40.230+0800        [A] ubuntu: GenerateBackupETCDService success (44.727929ms)
2024-12-17T19:52:40.273+0800        [A] ubuntu: GenerateBackupETCDTimer success (42.839457ms)
2024-12-17T19:52:40.396+0800        [A] ubuntu: EnableBackupETCDService success (122.621074ms)
2024-12-17T19:52:40.396+0800        [Module] InstallKubeBinariesModule
2024-12-17T19:52:41.188+0800        [A] ubuntu: SyncKubeBinary(k3s) success (791.866964ms)
2024-12-17T19:52:41.218+0800        [A] ubuntu: GenerateK3sKillAllScript success (30.442837ms)
2024-12-17T19:52:41.253+0800        [A] ubuntu: GenerateK3sUninstallScript success (34.802683ms)
2024-12-17T19:52:41.268+0800        [A] ubuntu: ChmodScript(k3s) success (14.640733ms)
2024-12-17T19:52:41.268+0800        [Module] K3sInitClusterModule
2024-12-17T19:52:41.334+0800        [A] ubuntu: GenerateK3sService success (66.556896ms)
2024-12-17T19:52:41.379+0800        [A] ubuntu: GenerateK3sServiceEnv success (44.492752ms)
2024-12-17T19:52:41.414+0800        [A] ubuntu: GenerateK3sRegistryConfig success (34.814475ms)
2024-12-17T19:52:46.511+0800        [A] ubuntu: EnableK3sService success (5.097800474s)
2024-12-17T19:52:46.572+0800        [A] ubuntu: CopyKubeConfig success (60.33887ms)
...

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.

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.

Example script output
bash
2024-12-17T19:53:18.382+0800        [A] ubuntu: InitKsNamespace success (2.678362348s)
2024-12-17T19:53:18.382+0800        [Module] DeploySnapshotController
customresourcedefinition.apiextensions.k8s.io/volumesnapshotclasses.snapshot.storage.k8s.io created
customresourcedefinition.apiextensions.k8s.io/volumesnapshotcontents.snapshot.storage.k8s.io created
customresourcedefinition.apiextensions.k8s.io/volumesnapshots.snapshot.storage.k8s.io created
2024-12-17T19:53:18.924+0800        [helm] app installed success        {"NAME": "snapshot-controller", "LAST DEPLOYED": "Tue Dec 17 19:53:18 2024", "NAMESPACE": "kube-system", "STATUS": "deployed", "REVISION": 1}
2024-12-17T19:53:18.924+0800        [A] ubuntu: CreateSnapshotController success (541.656132ms)
2024-12-17T19:53:18.924+0800        [Module] DeployRedis
secret/redis-secret created
2024-12-17T19:53:19.057+0800        [A] ubuntu: CreateRedisSecret success (133.123121ms)
2024-12-17T19:53:19.189+0800        [A] ubuntu: BackupRedisManifests success (132.045425ms)
2024-12-17T19:53:19.339+0800        [A] ubuntu: DeployRedisHA success (149.251633ms)
local (default)   openebs.io/local   Delete          WaitForFirstConsumer   false                  31s
local (default)   openebs.io/local   Delete   WaitForFirstConsumer   false   31s
2024-12-17T19:53:19.971+0800        [helm] app installed success        {"NAME": "redis", "LAST DEPLOYED": "Tue Dec 17 19:53:19 2024", "NAMESPACE": "kubesphere-system", "STATUS": "deployed", "REVISION": 1}
...

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 ​