eliott/Olares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add redirects and refactor studio docs

Browse Source
This commit is contained in:
yajing wang
2025-12-10 00:31:57 +08:00
parent 605b862937
commit 543328fa6e
10 changed files with 89 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/developer/develop/tutorial/assets.md Normal file
View File

@@ -0,0 +1,26 @@
---
description: Learn how to prepare and upload icons, feature image, and promotional images for your Olares apps.
---
# Add icons, feature image, and promotional images
A great-looking app needs high-quality assets. This guide covers the specifications for your app's icon, feature image, and screenshots, and how to upload them to Olares.
## Asset specifications
Before uploading, ensure your images are in the correct format.
| Type | Format | Max size | Dimensions (px) | Description |
|:----------------------|:----------------|:------------|:----------------|:----------------------------------------------------------------------------------------------------------------------|
| **App icon** | PNG, WEBP | 512 KB | 256x256 | Your app's most common visual symbol, used on the Olares desktop and throughout the system. |
| **Feature image** | JPEG, PNG, WEBP | 8 MB | 1440x900 | Displayed on your app's page in **Market** > **My Olares**. |
| **Promotional image** | JPEG, PNG, WEBP | 8 MB (each) | 1440x900 | If you plan to submit your app to the public Market, you must upload at least two. You can upload a maximum of eight. |
## Upload and link assets
1. Navigate to the [Olares Market Image Hosting service](https://imghost.joinolares.cn/).
2. Select the type of asset you are uploading (e.g., Icon).
3. Drag and drop your prepared file into the upload area, or click to select it.
4. Click the image thumbnail to make simple edits if necessary.
5. When you are ready, click **Upload**.
6. After the upload, the service will provide a direct URL for the image. Click <span class="material-symbols-outlined">content_copy</span> to copy the URL to your clipboard.
7. Open your app project in **Studio**.
8. Paste the URL into the corresponding field in your `OlaresManifest.yaml` file.

186
docs/developer/develop/tutorial/deploy.md Normal file
View File

@@ -0,0 +1,186 @@
---
outline: [2, 3]
description: Deploy a single-container Docker app to Olares using Studio.
---
# Deploy an app from Docker image
This guide explains how to deploy a single-container Docker app to Olares using Studio.
:::info For single-container apps
This method supports apps that run from a single container image. For multi-container apps (for example, a web service plus a separate database), use the workflow in the [developer documentation](index.md) instead.
:::
:::tip Recommended for testing
Studio-created deployments are best suited for development, testing, or temporary use. Upgrades and long-term data persistence can be limited compared to installing a packaged app from the Market. For production use, consider [packaging and uploading the app](package-upload.md) and installing it via the Market.
:::
## Prerequisites
- Olares version 1.12.2 or later.
- A container image for the app exists and is accessible from the Olares host.
- The app's `docker run` command or `docker-compose.yaml` is available to reference configuration (ports, environment variables, volumes).
## Create and configure your app
The following uses [Wallos](https://hub.docker.com/r/bellamy/wallos), a personal subscription and expense tracker, to show you how to map common Docker settings (image, ports, environment variables, volumes) into Studio.
**Docker examples**
::: code-group
```docker{3-6,8} [docker run command]
docker run -d \
--name wallos \
-v /path/to/config/wallos/db:/var/www/html/db \
-v /path/to/config/wallos/logos:/var/www/html/images/uploads/logos \
-e TZ=America/Toronto \
-p 8282:80 \
--restart unless-stopped \
bellamy/wallos:latest
```
```yaml{5-6,7-10,12-14} [docker compose]
version: '3.0'
services:
wallos:
container_name: wallos
image: bellamy/wallos:latest
ports:
- "8282:80/tcp"
environment:
TZ: 'America/Toronto'
# Volumes store your data between container upgrades
volumes:
- './db:/var/www/html/db'
- './logos:/var/www/html/images/uploads/logos'
restart: unless-stopped
```
:::
### Create an app
1. Open Studio and select **Create a new application**.
2. Enter an **App name**, for example: `wallos`, and click **Confirm**.
3. Select **Port your own container to Olares**.
![Port your own container to Olares](/images/manual/olares/studio-port-your-own-container-to-olares.png#bordered)
### Configure image, port, and instance spec
These fields define the app's core components. You can find this information as the main image name and the `-p` flag in a `docker run` command, or under the `image:` and `ports:` keys in a `docker-compose.yaml` file.
1. For the **Image** field, paste the image name: `bellamy/wallos:latest`.
2. For the **Port** field, from a `HOST:CONTAINER` mapping like `8282:80`, enter the Container Port only: `80`.
:::tip Container port only
A port mapping is defined as `HOST:CONTAINER`. The Container Port (after the colon) is the internal port the app listens on. The Host Port (before the colon) is the external port you access. Studio manages external access automatically, so you only need to enter the Container Port.
:::
3. For **Instance Specifications**, enter the minimum CPU and memory requirements. For example:
- **CPU**: 2 core
- **Memory**: 1 G
![Deploy Wallos](/images/manual/olares/studio-deploy-wallos.png#bordered)
### Add environment variables
Environment variables are used to pass configuration settings to your app. In the Docker examples, these are defined using the `-e` flag or in the `environment:` section.
1. Scroll down to **Environment Variables**, and click **Add**.
2. In this example, enter the key-value pair:
- **key**: `TZ`
- **value**: `America/Toronto`
3. Click **Submit**. Repeat this process for any other variables.
![Add environment variables](/images/manual/olares/studio-add-environment-variables.png#bordered)
### Add storage volumes
Volumes connect storage on your Olares device to a path inside the app's container, which is essential for saving data permanently. These are defined using the `-v` flag or in the `volumes:` section.
:::info Host path options
The host path is where Olares stores the data, and the mount path is the path inside the container. Olares provides three managed host path prefixes:
- `/app/data`: App data directory. Data can be accessed across nodes and is not deleted when the app is uninstalled. Appears under `/Data/studio` in Files.
- `/app/cache`: App cache directory. Data is stored in the node's local disk and is deleted when the app is uninstalled. Appears under `/Cache/<device-name>/studio` in Files.
- `/app/Home`: User data directory. Mainly used for reading external user files. Data is not deleted.
:::
:::info Host path rules
- The host path you enter *must* start with `/`.
- Studio automatically prefixes the full path with the app name. If the app name is `test` and you set host path `/app/data/folder1`, the actual path becomes `/Data/studio/test/folder1` in Files.
:::
This app requires two volumes. You will add them one by one.
1. Add the database volume. This data is for high-frequency I/O and does not need to be saved permanently. Map it to `/app/cache` so it will be automatically deleted when the app is uninstalled.
1. Click **Add** next to **Storage Volume**.
2. For **Host path**, select `/app/cache`, then enter `/db`.
3. For **Mount path**, enter `/var/www/html/db`.
4. Click **Submit**.
2. Add the logo volume. This is user-uploaded data that should be persistent and reusable, even if the app is reinstalled. Map it to `/app/data`.
1. Click **Add** next to **Storage Volume**.
2. For **Host path**, select `/app/data`, then enter `/logos`.
3. For **Mount path**, enter `/var/www/html/images/uploads/logos`
4. Click **Submit**.
![Add volumes](/images/manual/olares/studio-add-storage-volumes.png#bordered)
You can check Files later to verify the mounted paths.
![Check mounted path in Files](/images/manual/olares/studio-check-mounted-path-in-files.png#bordered)
### Optional: Configure GPU or database middleware
If your app needs GPU, enable the **GPU** option under **Instance Specifications** and select the GPU vendor.
![Enable GPU](/images/manual/olares/studio-enable-GPU.png#bordered)
If your app needs Postgres or Redis, enable it under **Instance Specifications**.
![Enable databases](/images/manual/olares/studio-enable-databases.png#bordered)
When enabled, Studio provides dynamic variables. You must use these variables in the **Environment Variables** section for your app to connect to the database.
- **Postgres variables:**
| Variables | Description |
|--------------|-----------------------|
| $(PG_USER) | PostgreSQL username |
| $(PG_DBNAME) | Database name |
| $(PG_PASS) | Postgres Password |
| $(PG_HOST) | Postgres service host |
| $(PG_PORT) | Postgres service port |
- **Redis variables:**
| Variables | Description |
|---------------|--------------------|
| $(REDIS_HOST) | Redis service host |
| $(REDIS_PORT) | Redis service port |
| $(REDIS_USER) | Redis username |
| $(REDIS_PASS) | Redis password |
### Generate the app project
1. Once all your configurations are set, click **Create**. This generates the app's project files.
2. After creation, Studio generates the package files for your app, and then automatically deploys the app. You can check the status in the bottom bar.
3. When the app is successfully deployed, click **Preview** in the top-right corner to launch it.
![Preveiw wallos](/images/manual/olares/studio-preview-wallos.png#bordered)
## Review the package files and test the app
Apps deployed from Studio include a `-dev` suffix in the title to distinguish them from Market installations.
![Check deployed app](/images/manual/olares/studio-app-with-dev-suffix.png#bordered)
You can click on files like `OlaresManifest.yaml` to review and make changes. For example, to change the app's display name and logo.
1. Click **<span class="material-symbols-outlined">box_edit</span>Edit** in the top-right to open the editor.
2. Click `OlaresManifest.yaml` to view the content.
3. Change the `title` field under `entrance` and `metadata`. For example, change `wallos` to `Wallos`.
4. Replace the default icon image address under `entrance` and `metadata`.
![Edit `OlaresManifest.yaml`](/images/manual/olares/studio-edit-olaresmanifest1.png#bordered)
5. Click <span class="material-symbols-outlined">save</span> in the top-right to save changes.
6. Click **Apply** to reinstall with the updated package.
:::info
If no changes are detected since the last deployment, clicking **Apply** will simply return to the app's status page without reinstalling.
:::
![Change app icon](/images/manual/olares/studio-change-app-icon1.png#bordered)
## Uninstall or delete the app
If you no longer need the app, you can remove it.
1. Click <span class="material-symbols-outlined">more_vert</span> in the top-right corner.
2. You can choose to:
- **Uninstall**: Removes the running app from Olares, but keeps the project in Studio so you can continue editing the package.
- **Delete**: Uninstalls the app and removes the project from Studio. This action is irreversible.
## Troubleshoot a deployment
### Cannot install the app
If installation fails, review the error at the bottom of the page and click **View** to expand details.
![Check app status](/images/manual/olares/studio-check-app-status.png#bordered)
### Run into issues when the app is running
Once running, you can manage the app from its deployment details page in Studio. The interface of this page is similar to Control Hub. If details don't appear, refresh the page.
You can:
- Use the **Stop** and **Restart** controls to retry. This action can often resolve runtime issues like a frozen process.
- Check events or logs to investigate runtime errors. See [Export container logs for troubleshooting](../../../manual/olares/controlhub/manage-container.md#export-container-logs-for-troubleshooting) for details.
![App deployment details](/images/manual/olares/studio-app-deployment-details.png#bordered)

238
docs/developer/develop/tutorial/develop.md Normal file
View File

@@ -0,0 +1,238 @@
---
outline: [2, 3]
description: Learn how to use Studio to set up a dev container, access it via VS Code, and configure port forwarding.
---
# Develop in a dev container
Olares Studio allows you to spin up a pre-configured dev container to write and debug code (such as Node.js scripts or CUDA programs) without managing local infrastructure. This provides an isolated environment identical to the production runtime.
The following guide shows the setup workflow using a Node.js project as an example.
:::info
This workflow is optimized for iterative coding and testing. If you intend to publish the application to the Olares Market, you must create your own image and follow the [developer documentation](../submit/index.md) for final configuration.
:::
## Prerequisite
- Olares version 1.12.2 or later.
## 1. Initialize the container
To start coding, you must provision the container resources and select your runtime environment.
1. Open Studio and select **Create a new application**.
2. Enter an **App name**, for example: `My Web`, and click **Confirm**.
3. Select **Coding on Olares** as the creation method.
![Coding on Olares](/images/manual/olares/studio-coding-on-olares.png#bordered)
4. Configure the **Dev Env**:
a. From the drop-down list, select `beclab/node20-ts-dev:1.0.0`.
b. Allocate the resources for the container. For example:
- **CPU**: `2 core`
- **Memory**: `4 Gi`
- **Volume Size**: `500 Mi`
5. In the **Expose Ports** field, enter the ports you intend to use for debugging (e.g., `8080`).
:::tip Expose multiple ports
Port `80` is exposed by default. Separate multiple additional ports with commas.
:::
![Configure Dev Env](/images/manual/olares/studio-configure-dev-env.png#bordered)
6. Click **Create**. Wait for the status in the bottom-left corner to change to `Running`.
## 2. Access the workspace
You can access your dev container via the browser or your local IDE.
### Option A: Browser-based VS Code
Click **code-server** in Studio. This launches a fully functional VS Code instance inside your browser.
![Open VS Code in browser](/images/manual/olares/studio-open-vs-code-in-browser.png#bordered)
### Option B: Local VS Code (Remote Tunnel)
If you prefer your local settings and extensions, you can tunnel into the container.
1. Click **code-server** in Studio to open the browser-based VS code.
2. Click <span class="material-symbols-outlined">menu</span> in the top left, and select **Terminal** > **New Terminal** to open the terminal.
3. Install the VS Code Tunnel CLI:
```bash
curl -SsfL https://vscode.download.prss.microsoft.com/dbazure/download/stable/17baf841131aa23349f217ca7c570c76ee87b957/vscode_cli_alpine_x64_cli.tar.gz | tar zxv -C /usr/local/bin
```
4. Create a secure tunnel:
```bash
code tunnel
```
5. Follow the terminal prompts to authenticate using a Microsoft or GitHub account via the provided URL.
6. Assign a name to the tunnel when prompted (e.g., `myapp-demo`). This will output a vscode.dev URL tied to this remote workspace.
![Create a secure tunnel](/images/manual/olares/studio-create-a-secure-tunnel.png#bordered)
7. Open VS Code on your local machine, click the **><** icon in the bottom-left, and select **Tunnel**.
![Open remote window](/images/manual/olares/studio-open-remote-window.png#bordered){width=30%}
![Connect remote tunnel](/images/manual/olares/studio-connect-remote-tunnel.png#bordered)
8. Log in with the same account used in the previous step.
9. Select the tunnel name you defined (e.g., `myapp-demo`). It may take a few minutes for VS Code to establish the connection. Once successful, the remote indicator in the bottom-left will display your tunnel name.
![Select tunnel name](/images/manual/olares/studio-select-tunnel-name.png#bordered)
![Remote tunnel connected](/images/manual/olares/studio-remote-tunnel-connected.png#bordered){width=30%}
Once connected, you have full remote access to the container's file system and terminal, mirroring a local development experience.
## 3. Write and run code
Once inside the workspace, either via browser or local tunnel, the workflow mirrors standard local development.
You can populate your workspace by:
- Uploading files
- Cloning a Git repository, or
- Creating files manually
This example demonstrates creating a basic web page manually.
1. Open the **Explorer** sidebar and navigate to `/root/`.
:::info
Studio persists project data at `Data/studio/<app_name>/`.
:::
![Open root directory](/images/manual/olares/studio-open-root-directory.png#bordered)
2. Click <span class="material-symbols-outlined">menu</span> in the top left, and select **Terminal** > **New Terminal** to open the terminal.
3. Run the following command to initialize the project:
```bash
npm init -y
```
4. Install the Express framework:
```bash
npm install express --save
```
5. Create a file named `index.js` in `/root/` with the following content:
```js
// Ensure the port matches what you defined
const express = require('express');
const app = express();
app.use(express.static('public/'));
app.listen(8080), function() {
console.log('Server is running on port 8080');
};
```
6. Create a `public` directory in `/root/` and add an `index.html` file:
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>My Web Page</title>
</head>
<body>
<h1>Hello World</h1>
<h1>Hello Olares</h1>
</body>
</html>
```
7. Start the server:
```bash
node index.js
```
8. Open the **Ports** tab in VS Code and click the forwarded address to view the result.
![View web page](/images/manual/olares/studio-view-web-page.png#bordered)
## 4. Configure port forwarding
If you need to expose additional ports after the container is created (e.g., adding port `8081`), you must manually edit the container configuration manifests.
:::tip
You can follow the same steps to modify `OlaresManifest.yaml` and `deployment.yaml` to change the port number.
:::
### Modify configuration manifests
1. In Studio, click **<span class="material-symbols-outlined">box_edit</span>Edit** in the top-right to open the editor.
2. Edit `OlaresManifest.yaml`.
a. Append the new port to the `entrances` list:
```yaml
entrances:
- authLevel: private
host: myweb
icon: https://app.cdn.olares.com/appstore/default/defaulticon.webp
invisible: true
name: myweb-dev-8080
openMethod: ""
port: 8080
skip: true
title: myweb-dev-8080
# Add the following
- authLevel: private
host: myweb # Must match Service metadata name
icon: https://app.cdn.olares.com/appstore/default/defaulticon.webp
invisible: true
name: myweb-dev-8081 # Unique identifier
openMethod: ""
port: 8081 # The new port number
skip: true
title: myweb-dev-8081
```
b. Click <span class="material-symbols-outlined">save</span> in the top-right to save changes.
3. Edit `deployment.yaml`.
a. Add the port mapping to `default-thirdlevel-domains` under `Deployment` > `metadata`:
```yaml
annotations:
applications.app.bytetrade.io/default-thirdlevel-domains:
'[{"appName":"myweb","entranceName":"myweb-dev-8080"},{"appName":"myweb","entranceName":"myweb-dev-8081"}]'
# entranceName must match the name used in OlaresManifest.yaml
```
b. Update the `studio-expose-ports` annotation under `spec` > `template` > `metadata`:
```yaml
template:
metadata:
annotations:
applications.app.bytetrade.io/studio-expose-ports: "8080,8081"
```
c. Add the port definition under `Service` > `spec` > `ports`:
```yaml
kind: Service
spec:
ports:
- name: "80"
port: 80
targetPort: 80
# Add the following
- name: myweb-dev-8081 # Must match entrance name
port: 8081
targetPort: 8081
selector:
io.kompose.service: myweb
```
d. Click <span class="material-symbols-outlined">save</span> in the top-right to save changes.
4. Click **Apply** to redeploy the container.
You can verify the active ports in **Services** > **Ports**.
![Verify active ports](/images/manual/olares/studio-verify-active-ports.png#bordered)
### Verify the new port
1. Update `index.js` to listen on the new port:
```js
const express = require('express');
const app = express();
app.use(express.static('public/'));
app.listen(8080), function() {
console.log('Server is running on port 8080');
};
// Add the following
const app_new = express();
app_new.use(express.static('new/'));
app_new.listen(8081), function() {
console.log('Server is running on port 8081');
};
```
2. Create a `new` directory in `/root/` and add an `index.html` file:
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>My Web Page</title>
</head>
<body>
<h1>This is a new page</h1>
</body>
</html>
```
3. Restart the server:
```bash
node index.js
```
4. Check the **Ports** tab to confirm port `8081` is active and accessible.
![View added port](/images/manual/olares/studio-view-added-port.png#bordered)
5. Click the forwarded address to view the result.
![Verify added web page](/images/manual/olares/studio-verify-added-web-page.png#bordered)

29
docs/developer/develop/tutorial/index.md
View File

@@ -1,15 +1,26 @@
# Tutorial
---
description: Get started with Studio to deploy Docker-based apps, develop new apps, package and upload locally, and manage assets on your Olares device.
---
# Deploy and develop apps in Olares
Welcome to the Olares developer guides. These detailed tutorials offer a step-by-step guide on building an Olares Application from scratch.
Studio provides a real Olares environment for building, porting, and testing apps when cloud features and the sandbox system are hard to simulate locally. With Studio you can:
- Create a new Olares app in an online development container.
- Port an existing app, adjust its configurations, and test the installation flow.
-Package your app into a chart and download it when your app is ready.
To get started, you can learn some basic concepts of Olares, such as:
- [Olares architectural components](../../concepts/architecture.md)
- [Olares Application Chart](../../develop/package/chart.md)
- [Olares Extension on Helm](../package/extension.md)
## Access Studio
Studio is available in Olares Market and must be installed manually.
1. Open **Market**, and search for "Studio".
![Studio](/images/manual/olares/studio.png#bordered)
These fundamentals will help you grasp our development process more effectively.
2. Click **Get**, then **Install**, and wait for installation to complete.
You can also [learn about DevBox](studio.md), a built-in app that Olares provides for developers to build Olares applications.
After installation, launch Studio from Market or from Launchpad.
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.
## Understand the Studio UI
The sidebar and **Home** page organize your main tasks in Studio:
- **Home**: A welcome page with shortcuts to common actions and documentation.
- **Applications**: A list of apps you have created and deployed with Studio.
- **Start**: You can start deploying or developing apps, or uploading an app from a local chart file.
![Understand Studio user interface](/images/manual/olares/studio-ui.png#bordered)

29
docs/developer/develop/tutorial/package-upload.md Normal file
View File

@@ -0,0 +1,29 @@
---
description: Download an app package from Studio and install it in the Olares Market for stable, long-term use.
---
# Package and upload your app to Market
Apps created in Studio are ideal for development and testing. For stable, long-term use, it is best to install them through the Olares Market.
## Download the App package from Studio
After confirming that your app works as expected, you can download its complete installation package.
1. Open your app project in **Studio**.
2. Click <span class="material-symbols-outlined">more_vert</span> in the top-right corner.
3. Select **Download** from the dropdown menu to save the app package to your local machine.
## Install the App via the Market
1. Open the **Market** app.
2. Navigate to the **My Olares** section and select **Upload custom chart**.
3. Select the app package file (`.tgz`) you downloaded from Studio. Wait for the upload to complete.
4. A pop-up will appear confirming the app was successfully added. Click **Install now**.
![Install custom chart](/images/manual/olares/studio-custom-install.png#bordered)
Once finished, you can click **Open** to launch it.
All custom-installed apps will appear under the **My Olares** > **Upload** tab.