From 8e54a0cc8265921e7dbdbb432440dae2f4843bfe Mon Sep 17 00:00:00 2001 From: Gao Hanxiang Date: Mon, 26 Jul 2021 10:55:55 -0400 Subject: [PATCH] docs: Add quick start docs 1. Add a quick start, the document explains how to use the container to quickly deploy the skyline service. 2. Modify the format of the original `Development skyline-apiserver` section. Change-Id: I4ff1c179791b782311be4d8c391565bfcaf16bf9 --- README-zh_CN.md | 179 ++++++++++++++++++++++++++++++++++++++---------- README.md | 177 +++++++++++++++++++++++++++++++++++++---------- 2 files changed, 283 insertions(+), 73 deletions(-) diff --git a/README-zh_CN.md b/README-zh_CN.md index 9bec8b9..fdb8d96 100644 --- a/README-zh_CN.md +++ b/README-zh_CN.md @@ -1,61 +1,166 @@ -# Skyline API +# Skyline [English](./README.md) | 简体中文 +Skyline 是一个经过 UI 和 UE 优化过的 OpenStack 仪表盘, 拥有现代化的技术栈和生态，更易于开发者维护和使用者操作, 以及更高的并发性能. + +**目录** + +- [资源](#资源) +- [快速开始](#快速开始) +- [开发 Skyline-apiserver](#开发-skyline-apiserver) + +## 资源 + +- [Wiki](https://wiki.openstack.org/wiki/Skyline) +- [Bug 跟踪器](https://launchpad.net/skyline-apiserver) + ## 快速开始 +### 先决条件 + +- 一个至少运行核心组件的 OpenStack 环境, 并能通过 Keystone endpoint 访问 OpenStack 组件 +- 一个安装有容器引擎的 ([docker](https://docs.docker.com/engine/install/) 或 [podman](https://podman.io/getting-started/installation)) 的 Linux 服务器 + +### 配置和部署 + +#### 1. 连接 OpenStack 环境的数据库, 并创建 `skyline` 数据库 + +```bash +$ mysql -u root -p +MariaDB [(none)]> CREATE DATABASE IF NOT EXISTS skyline DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; +Query OK, 1 row affected (0.001 sec) +``` + +#### 2. 授予对数据库的适当访问权限 + +用合适的密码替换 `SKYLINE_DBPASS` + +```bash +MariaDB [(none)]> GRANT ALL PRIVILEGES ON skyline.* TO 'skyline'@'localhost' IDENTIFIED BY 'SKYLINE_DBPASS'; +Query OK, 0 rows affected (0.001 sec) + +MariaDB [(none)]> GRANT ALL PRIVILEGES ON skyline.* TO 'skyline'@'%' IDENTIFIED BY 'SKYLINE_DBPASS'; +Query OK, 0 rows affected (0.001 sec) +``` + +#### 3. 创建 skyline 服务凭证 + +```bash +# Source the admin credentials +$ source admin-openrc + +# Create the skyline user +$ openstack user create --domain default --password-prompt skyline +User Password: +Repeat User Password: ++---------------------+----------------------------------+ +| Field | Value | ++---------------------+----------------------------------+ +| domain_id | default | +| enabled | True | +| id | 1qaz2wsx3edc4rfv5tgb6yhn7ujm8ikl | +| name | skyline | +| options | {} | +| password_expires_at | 2020-08-08T08:08:08.123456 | ++---------------------+----------------------------------+ + +# Add the admin role to the skyline user: +$ openstack role add --project service --user skyline admin +``` + +#### 4. 在 Linux 服务器中编辑 `/etc/skyline/skyline.yaml` 文件 + +可以参考 [sample file](etc/skyline.yaml.sample), 并根据实际的环境修改以下参数 + +- database_url +- keystone_url +- default_region +- interface_type +- system_project_domain +- system_project +- system_user_domain +- system_user_name +- system_user_password + +#### 5. 运行 skyline_bootstrap 容器进行初始化引导 + +```bash +docker run -d --name skyline_bootstrap -e KOLLA_BOOTSTRAP="" -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host skyline:latest + +# Check bootstrap is normal `exit 0` +docker logs skyline_bootstrap +``` + +#### 5. 初始化引导完成后运行 skyline 服务 + +```bash +docker rm -f skyline_bootstrap + +docker run -d --name skyline --restart=always -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host skyline:latest +``` + +#### 6. 完成安装 + +现在你可以访问仪表盘: `https://:8080` + +## 开发 Skyline-apiserver + +**支持 Linux 和 Mac 操作系统 (推荐 Linux 操作系统) (由于 uvloop 和 cython 库)** + ### 依赖工具 - make >= 3.82 - poetry >= 1.1.0 ([安装指南](https://python-poetry.org/docs/#installation)) -### 开发模式 +### 安装和运行 -**支持 Linux 和 Mac 操作系统 (推荐 Linux 操作系统) (由于 uvloop 和 cython 库)** +#### 1. 安装依赖包 -- 安装依赖包 +```bash +make install +``` - ```bash - make install - ``` +#### 2. 配置 `skyline.yaml` 文件 -- 配置 skyline.yaml 文件 +```bash +cp etc/skyline.yaml.sample etc/skyline.yaml +export OS_CONFIG_DIR=$(pwd)/etc +``` - 可能你需要根据实际的环境修改以下参数： +可能你需要根据实际的环境修改以下参数： - ```yaml - - database_url (你可以设置为 sqlite:////tmp/skyline.db 来使用 sqlite) - - default_region - - keystone_url - - system_project - - system_project_domain - - system_user_domain - - system_user_name - - system_user_password - ``` +```yaml +- database_url (你可以设置为 sqlite:///tmp/skyline.db 来使用 sqlite) +- keystone_url +- default_region +- interface_type +- system_project_domain +- system_project +- system_user_domain +- system_user_name +- system_user_password +``` - ```bash - cp etc/skyline.yaml.sample etc/skyline.yaml - export OS_CONFIG_DIR=$(pwd)/etc - ``` +#### 3. 初始化 skyline 数据库 -- 初始化 skyline 数据库 +```bash +pushd /skyline/libs/skyline-apiserver/ +make db_sync +popd +``` - ```bash - make db_sync - ``` +#### 4. 运行 skyline-apiserver -- 运行服务 +```bash +$ poetry run uvicorn --reload --reload-dir libs/skyline-apiserver/skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app - ```console - $ poetry run uvicorn --reload --reload-dir libs/skyline-apiserver/skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app - - INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) - INFO: Started reloader process [154033] using statreload - INFO: Started server process [154037] - INFO: Waiting for application startup. - INFO: Application startup complete. - ``` +INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) +INFO: Started reloader process [154033] using statreload +INFO: Started server process [154037] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` 此时你可访问在线 API 文档：`http://127.0.0.1:28000/docs` diff --git a/README.md b/README.md index de215af..b650149 100644 --- a/README.md +++ b/README.md @@ -2,60 +2,165 @@ English | [简体中文](./README-zh_CN.md) +Skyline is an OpenStack dashboard optimized by UI and UE. It has a modern technology stack and ecology, is easier for developers to maintain and operate by users, and has higher concurrency performance. + +**Table of contents** + +- [Resources](#resources) +- [Quick Start](#quick-start) +- [Develop Skyline-apiserver](#develop-skyline-apiserver) + +## Resources + +- [Wiki](https://wiki.openstack.org/wiki/Skyline) +- [Bug Tracker](https://launchpad.net/skyline-apiserver) + ## Quick Start +### Prerequisites + +- An OpenStack environment that runs at least core components and can access OpenStack components through Keystone endpoints +- A Linux server with container engine ([docker](https://docs.docker.com/engine/install/) or [podman](https://podman.io/getting-started/installation)) installed + +### Configure and deployment + +#### 1. Connect to database of the OpenStack environment and create the `skyline` database + +```bash +$ mysql -u root -p +MariaDB [(none)]> CREATE DATABASE IF NOT EXISTS skyline DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; +Query OK, 1 row affected (0.001 sec) +``` + +#### 2. Grant proper access to the databases + +Replace `SKYLINE_DBPASS` with a suitable password. + +```bash +MariaDB [(none)]> GRANT ALL PRIVILEGES ON skyline.* TO 'skyline'@'localhost' IDENTIFIED BY 'SKYLINE_DBPASS'; +Query OK, 0 rows affected (0.001 sec) + +MariaDB [(none)]> GRANT ALL PRIVILEGES ON skyline.* TO 'skyline'@'%' IDENTIFIED BY 'SKYLINE_DBPASS'; +Query OK, 0 rows affected (0.001 sec) +``` + +#### 3. Create skyline service credentials + +```bash +# Source the admin credentials +$ source admin-openrc + +# Create the skyline user +$ openstack user create --domain default --password-prompt skyline +User Password: +Repeat User Password: ++---------------------+----------------------------------+ +| Field | Value | ++---------------------+----------------------------------+ +| domain_id | default | +| enabled | True | +| id | 1qaz2wsx3edc4rfv5tgb6yhn7ujm8ikl | +| name | skyline | +| options | {} | +| password_expires_at | 2020-08-08T08:08:08.123456 | ++---------------------+----------------------------------+ + +# Add the admin role to the skyline user: +$ openstack role add --project service --user skyline admin +``` + +#### 4. Edit the `/etc/skyline/skyline.yaml` file in linux server + +You can refer to the [sample file](etc/skyline.yaml.sample), and modify the following parameters according to the actual environment + +- database_url +- keystone_url +- default_region +- interface_type +- system_project_domain +- system_project +- system_user_domain +- system_user_name +- system_user_password + +#### 5. Run the skyline_bootstrap container to bootstrap + +```bash +docker run -d --name skyline_bootstrap -e KOLLA_BOOTSTRAP="" -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host skyline:latest + +# Check bootstrap is normal `exit 0` +docker logs skyline_bootstrap +``` + +#### 5. Run the skyline service after bootstrap is complete + +```bash +docker rm -f skyline_bootstrap + +docker run -d --name skyline --restart=always -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host skyline:latest +``` + +#### 6. finish installation + +You can now access the dashboard: `https://:8080` + +## Develop Skyline-apiserver + +**Support Linux & Mac OS (Recommend Linux OS) (Because uvloop & cython)** + ### Dependent tools - make >= 3.82 - poetry >= 1.1.0 ([Installation Guide](https://python-poetry.org/docs/#installation)) -### Development mode +### Install & Run -**Support Linux & Mac OS (Recommend Linux OS) (Because uvloop & cython)** +#### 1. Installing dependency packages -- Installing dependency packages +```bash +make install +``` - ```bash - make install - ``` +#### 2. Set skyline.yaml config file -- Set skyline.yaml config file +```bash +cp etc/skyline.yaml.sample etc/skyline.yaml +export OS_CONFIG_DIR=$(pwd)/etc +``` - Maybe you should change the params with your real environment as followed: +Maybe you should change the params with your real environment as followed: - ```yaml - - database_url (you can set sqlite:////tmp/skyline.db to use sqlite) - - default_region - - keystone_url - - system_project - - system_project_domain - - system_user_domain - - system_user_name - - system_user_password - ``` +```yaml +- database_url (you can set sqlite:////tmp/skyline.db to use sqlite) +- keystone_url +- default_region +- interface_type +- system_project_domain +- system_project +- system_user_domain +- system_user_name +- system_user_password +``` - ```bash - cp etc/skyline.yaml.sample etc/skyline.yaml - export OS_CONFIG_DIR=$(pwd)/etc - ``` +#### 3. Init skyline database -- Init skyline database +```bash +pushd /skyline/libs/skyline-apiserver/ +make db_sync +popd +``` - ```bash - make db_sync - ``` +#### 4. Run skyline-apiserver -- Run server +```bash +$ poetry run uvicorn --reload --reload-dir libs/skyline-apiserver/skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app - ```console - $ poetry run uvicorn --reload --reload-dir libs/skyline-apiserver/skyline_apiserver --port 28000 --log-level debug skyline_apiserver.main:app - - INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) - INFO: Started reloader process [154033] using statreload - INFO: Started server process [154037] - INFO: Waiting for application startup. - INFO: Application startup complete. - ``` +INFO: Uvicorn running on http://127.0.0.1:28000 (Press CTRL+C to quit) +INFO: Started reloader process [154033] using statreload +INFO: Started server process [154037] +INFO: Waiting for application startup. +INFO: Application startup complete. +``` You can now access the online API documentation: `http://127.0.0.1:28000/docs`