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

feat: add docs to main (#1559)

Browse Source
This commit is contained in:
Peng Peng
2025-07-17 11:58:59 +08:00
committed by GitHub
parent e00018de59
commit af8e3b172c
1037 changed files with 40779 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/developer/develop/tutorial/index.md Normal file
View File

@@ -0,0 +1,15 @@
# 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.

71
docs/developer/develop/tutorial/note/backend.md Normal file
View File

@@ -0,0 +1,71 @@
# Develop Backend Program
## Clone Code
Open the IDE of backend Dev Container, open Terminal, clone your code to the `/Code` directory
```sh
gh auth login
cd /Code
git clone https://github.com/beclab/terminus-app-demo.git
```
You can then open the backend code in the IDE for development.
![server IDE](/images/developer/develop/tutorial/backend/dev.jpg)
## Connect Database
In the Dev Container, you can access database details through environment variables. You can do this by adding the database parameters into the container using environment variables when you deploy it.
Take `gorm` as an example:
```go
import (
"fmt"
"os"
"strconv"
"gorm.io/driver/postgres"
"gorm.io/gorm"
)
func init() {
var err error
db_host = os.Getenv("DB_HOST")
db_port, err = strconv.Atoi(os.Getenv("DB_PORT"))
if err != nil {
panic(err)
}
db_username = os.Getenv("DB_USER")
db_password = os.Getenv("DB_PWD")
db_name = os.Getenv("DB_NAME")
}
func main(){
dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable TimeZone=Asia/Shanghai",
db_host, db_username, db_password, db_name, db_port)
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
if err != nil {
panic(err)
}
}
```
## Debug
After completing the development, you can run and debug your code in the IDE.
![run and debug](/images/developer/develop/tutorial/backend/debug.jpg)
You can also run your code in the Terminal, for example:
```sh
go run main.go
```
Now, you can debug your interface with your front-end program.

201
docs/developer/develop/tutorial/note/create.md Normal file
View File

@@ -0,0 +1,201 @@
---
outline: [2, 3]
---
# How to Start Developing an Application
## Install and Launch DevBox
1. Install [DevBox](https://market.olares.com/app/devbox) from the Olares Market.
2. Find the DevBox icon in the launcher panel on the Olares Desktop.
3. Click on the icon to launch the application.
![main screen](/images/developer/develop/tutorial/create/home.jpg)
## Create Your App
Click the **Create a new application** to create a blank Olares application from a template.
- In the **App Name** field, enter your application name.
- Set the **APP type** to **app**.
- Change the **Main Entrance Port** for your APP entrance.
- In the **Image** field, input the image name and tag from your image repository where your app image will be stored.
![create app](/images/developer/develop/tutorial/create/create.jpg)
## Setup App Config
After creating the application, you can see the Olares Application Chart files generated by DevBox under the **Files** Tab. You can add, delete, or rename various configuration files as needed.
![upload icon](/images/developer/develop/tutorial/create/add-file.jpg)
### Chart.yaml
The `Chart.yaml` file is a required file in the Helm Chart specification. It contains the application's `Name` and `Chart Version`. You can [learn more here](https://helm.sh/docs/topics/charts/). For now, we're not going to change the default `Chart.yaml` yet.
### OlaresManifest.yaml
In the `OlaresManifest.yaml `file, you can change many configurations. This includes but is not limited to:
- Changing the app's title, icon, and other details
- Adding system `middleware`
- Getting `permissions` for system directory access
- Changing the `required and limited resource` of the app
#### Adding a [cluster database middleware](../../package/manifest.md#middleware)
![config app](/images/developer/develop/tutorial/create/olares-manifest.jpg)
In this example, we will configure a PostgreSQL database. Add the following content to the configuration file:
```Yaml
middleware:
postgres:
username: postgres
databases:
- name: db
distributed: false
```
You can specify your database `username` and `password` in the configuration. Alternatively, you can leave these fields empty and use the system-generated random password instead. You need to set the database `name` required by your APP. In addition, you can also choose to apply for a `distributed database`. If so, the system will create a [citus](https://github.com/citusdata/citus) database for you.
After completing the configuration, you can reference the corresponding database configuration in your `deployment.yaml`. For example, reference in the environment variables of the container.
```yaml
- env:
- name: DB_PORT
value: "{{ .Values.postgres.port }}"
- name: DB_NAME
value: "{{ .Values.postgres.databases.demo }}"
- name: DB_USER
value: "{{ .Values.postgres.username }}"
- name: DB_HOST
value: "{{ .Values.postgres.host }}"
- name: DB_PWD
value: "{{ .Values.postgres.password }}"
```
- `.Values.postgres.username`: the `username` of PostgreSQL in configuration.
- `.Values.postgres.databases.demo`: the `database name` in configuration.
- `.Values.postgres.password`: the `password` in configuration.
- `.Values.postgres.host`: the database service address specified by the system for the APP.
- `.Values.postgres.port`: the database service port specified by the system for the APP.
::: warning
These parameters should not be hardcoded, they must reference the variables passed in by the system, and the system will randomize the database information in the configuration.
:::
#### Adding [Access Permissions to the File System](../../package/manifest.md#permission)
To read and save files in the Olares system, we need to configure Access Permissions for certain file directories. These directories can be specified in the `Permissions` section of the `OlaresManifest.yaml` file:
- `appData`: This applies for independent cloud storage space for the app.
- `appCache`: This applies for local disk data cache space, usually on an SSD disk, for the app.
- `userData`: This applies for access permission to the user's data directory. List the directories you need to access here.
After completing the above configuration, you can reference these configurations in your deployment
```yaml
volumes:
- hostPath:
path: "{{ .Values.userspace.appCache }}/demo"
type: DirectoryOrCreate
name: appcache
- hostPath:
path: "{{ .Values.userspace.appData }}/demo"
type: DirectoryOrCreate
name: appdata
```
- `.Values.userspace.appCache` is the `appCache` directory
- `.Values.userspace.appData` is the `appData` directory
- `.Values.userspace.userData` is the `userData` directory
### deployment.yaml
The `deployment.yaml` in the `templates` folder details the deployment configuration of your application.
If your app includes several containers, such as front-end and back-end, you can add multiple containers in the `deployment.yaml` file in the `templates`. DevBox will recognize these different containers and bind each of them separately to different development containers. For example:
```yaml
containers:
# front-end container
- env:
- name: PGID
value: "1000"
- name: PUID
value: "1000"
- name: TZ
value: Etc/UTC
image: bytetrade/demo-app:0.0.1
name: demo
ports:
- containerPort: 8080
resources:
limits:
cpu: "1"
memory: 2000Mi
requests:
cpu: 50m
memory: 1000Mi
volumeMounts:
- mountPath: /appcache
name: appcache
# Server container
- env:
- name: DB_PORT
value: "{{ .Values.postgres.port }}"
- name: DB_NAME
value: "{{ .Values.postgres.databases.demo }}"
- name: DB_USER
value: "{{ .Values.postgres.username }}"
- name: DB_HOST
value: "{{ .Values.postgres.host }}"
- name: DB_PWD
value: "{{ .Values.postgres.password }}"
- name: PGID
value: "1000"
- name: PUID
value: "1000"
- name: TZ
value: Etc/UTC
image: bytetrade/demo-server:0.0.1
name: server
ports:
- containerPort: 9000
resources:
limits:
cpu: "1"
memory: 1000Mi
requests:
cpu: 50m
memory: 500Mi
volumeMounts:
- mountPath: /appcache
name: appcache
- mountPath: /appdata
name: appdata
```
## Bind Container
After configuring the above details, navigate to the **Containers** page to bind the development container(**Dev Container**) for this app. Once done, you can start coding.
![containers](/images/developer/develop/tutorial/create/bind.jpg)
You can set a specified development environment for the bound **Dev Container**. Currently, DevBox supports `NodeJS`, `Golang`, and `Python` **Dev Container**. Let's bind a `NodeJS` **Dev Container** to the demo frontend container and a `Golang` **Dev Container** to the server container.
We create a new **Dev Container** here. If you have previously created an unbound **Dev Container**, you can also choose an existing container for binding here.
![bind container](/images/developer/develop/tutorial/create/bind-2.jpg)
## Install App
After binding the **Dev Container**, click **Install** in the upper right corner to install the development app into the system. Once the installation status shifts from `Processing` to `Running`, it indicates that the app is installed and ready for coding.
![installing](/images/developer/develop/tutorial/create/installing.jpg)
Then, navigate back to the **Containers** page. You'll notice that the **Open IDE button** is now enabled. Press this button to access the **Dev Container** and begin coding in the actual environment.
![processing](/images/developer/develop/tutorial/create/success.jpg)

74
docs/developer/develop/tutorial/note/frontend.md Normal file
View File

@@ -0,0 +1,74 @@
# Develop Frontend Program
## Preview App
After installing the app, you can preview the frontend of your application using the **Preview** button in **DevBox**.
![preview](/images/developer/develop/tutorial/frontend/preview.jpg)
## Open IDE
When you open the frontend **Dev Contain IDE, you'll see the welcome page. From this point, the steps are like those for [backend development](backend.md). You can clone your frontend code using the Terminal.
::: tip
In this example, the frontend and backend use the same code directory. So, after you've cloned the code for the backend, you don't need to do it again.
:::
After cloning the code, if you are working on a Node project, you might need to make some configuration changes.
- **Vite Configuration Changes**
If your frontend project uses **Vite**, you need to add an **HMR** configuration. In development mode, **Vite** initiates a **WebSocket** to receive code reload notifications from the server. The default **WebSocket** port matches the server's startup port. However, if the development app uses an **Nginx proxy** it will operate on the default port 443. Therefore, some modifications are required.
Modify the `vite.config.js` file as follows:
```js
export default defineConfig({
server: {
hmr: {
clientPort: 443,
},
},
});
```
- **Nginx Configuration Changes**
After setting up your project's development environment, you need to modify the Nginx configuration. Open `/etc/nginx/conf.d/dev/dev.conf` and make the necessary changes:
```nginx
location / {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $http_host;
proxy_set_header X-real-ip $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_set_header Accept-Encoding gzip;
}
```
Then, reload Nginx:
```sh
nginx -s reload
```
## Run Dev Mode
After completing the **Nginx** configuration, you can start your frontend program in dev mode and preview your APP in Olares.
```sh
npm run dev
```
![frontend preview](/images/developer/develop/tutorial/frontend/preview2.jpg)
If you need to set up a backend api proxy for the frontend, you can modify the proxy configuration in **Nginx**.
```nginx
location /api/ {
proxy_pass http://127.0.0.1:9001;
proxy_set_header Host $http_host;
proxy_set_header X-real-ip $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_set_header Accept-Encoding gzip;
}
```

16
docs/developer/develop/tutorial/note/index.md Normal file
View File

@@ -0,0 +1,16 @@
# 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)<br>
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)<br>
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)<br>
In this section, you'll learn how to use DevBox's IDE to develop frontend pages, using `NodeJS` as an example.

13
docs/developer/develop/tutorial/studio.md Normal file
View File

@@ -0,0 +1,13 @@
# Learn about DevBox
At Olares, we provide a development tool called DevBox. It helps developers create applications for **Olares**.
- Why is DevBox necessary for developers?
Olares has many cloud-based features that are difficult to simulate in a standalone development environment. Furthermore, the unique sandbox system of **Olares** requires a real system environment for end-to-end testing. To simplify app simulation for developers and minimize system integration efforts during development, we provide the **DevBox**. **DevBox** is a quick, automatic toolset for creating app sandboxes.
- What features does DevBox have?
- In DevBox, you can build an app and generate a corresponding Olares Application Configuration* This deployment files can be modified, allowing you to port an existing app and deploy it to the Olares. During the modification process, you can continually attempt installation and resolve any issues that arise. Once the app passes your tests, you can download your Application Chart and submit it to the [Olares Market Repository](https://github.com/beclab/apps).
- In addition to porting existing apps, you can also create a native Olares application in DevBox. DevBox provides an online development container where coders can work in a real environment, utilize other system interfaces, database clusters, and more.