diff --git a/README-zh_CN.rst b/README-zh_CN.rst index 3a3c7e2..09bb886 100644 --- a/README-zh_CN.rst +++ b/README-zh_CN.rst @@ -2,6 +2,8 @@ OpenStack Skyline APIServer =========================== +`English <./README.rst>`__ \| 简体中文 + Skyline 是一个经过 UI 和 UE 优化过的 OpenStack 仪表盘，支持 OpenStack Train 及以上版本。Skyline 拥有现代化的技术栈和生态，更易于开发者维护和 使用者操作，以及更高的并发性能。 @@ -11,6 +13,8 @@ Skyline 的吉祥物是九色鹿。九色鹿源自于敦煌壁画《九色鹿本 Skyline 像九色鹿一样，轻巧、优雅，而又能力强大，为 OpenStack 社区和用户 提供更优质的 Dashboard。 +|image0| + **目录** - `Skyline API Server <#skyline-api-server>`__ @@ -35,6 +39,8 @@ Skyline 像九色鹿一样，轻巧、优雅，而又能力强大，为 OpenStac 资源 ---- +- `开发者手册 `__ +- `发布小结 `__ - `Wiki `__ - `Bug 跟踪器 `__ @@ -276,4 +282,5 @@ Kolla Ansible 部署 |image1| +.. |image0| image:: doc/source/images/logo/OpenStack_Project_Skyline_horizontal.png .. |image1| image:: doc/source/images/logo/nine-color-deer-64.png diff --git a/README.rst b/README.rst index 0a5599e..10744ef 100644 --- a/README.rst +++ b/README.rst @@ -1,35 +1,295 @@ -=========================== -OpenStack Skyline APIServer -=========================== +================== +Skyline API Server +================== -.. image:: https://governance.openstack.org/tc/badges/skyline-apiserver.svg - :target: https://governance.openstack.org/tc/reference/tags/index.html +English \| `简体中文 <./README-zh_CN.rst>`__ -.. Change things from this point on +Skyline is an OpenStack dashboard optimized by UI and UE, support +OpenStack Train+. It has a modern technology stack and ecology, is +easier for developers to maintain and operate by users, and has higher +concurrency performance. -OpenStack Skyline APIServer is the back-end server of Skyline. +Skyline's mascot is the nine-color deer. The nine-color deer comes from +Dunhuang mural “the nine-color king deer”, whose moral is Buddhist +cause-effect and gratefulness, which is consistent with 99cloud's +philosophy of embracing and feedback community since its inception. We +also hope Skyline can keep light, elegant and powerful as the nine-color +deer, to provide a better dashboard for the openstack community and +users. -Skyline is an OpenStack dashboard optimized by UI and UE, support OpenStack -Train+. It has a modern technology stack and ecology, is easier for developers -to maintain and operate by users, and has higher concurrency performance. +|image0| -You can learn more about Skyline APIServer at: +**Table of contents** -* `Wiki `__ -* `Developer Docs `__ -* `Blueprints `__ -* `Release notes `__ +- `Skyline API Server <#skyline-api-server>`__ -Getting Started ---------------- + - `Resources <#resources>`__ + - `Quick Start <#quick-start>`__ -If you'd like to run from the master branch, you can clone the git repo: + - `Prerequisites <#prerequisites>`__ + - `Configure <#configure>`__ + - `Deployment with Sqlite <#deployment-with-sqlite>`__ + - `Deployment with MariaDB <#deployment-with-mariadb>`__ + - `Test Access <#test-access>`__ - git clone https://opendev.org/openstack/skyline-apiserver + - `Develop Skyline-apiserver <#develop-skyline-apiserver>`__ -You can raise bugs on `Launchpad `__ + - `Dependent tools <#dependent-tools>`__ + - `Install & Run <#install--run>`__ + + - `Devstack Integration <#devstack-integration>`__ + - `Kolla Ansible Deployment <#kolla-ansible-deployment>`__ + +Resources +--------- + +- `Developer Docs `__ +- `Release notes `__ +- `Wiki `__ +- `Bug Tracker `__ + +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 `__ or + `podman `__) + installed + +Configure +~~~~~~~~~ + +1. Edit the ``/etc/skyline/skyline.yaml`` file in linux server + + You can refer to the `sample file `__, 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 + +Deployment with Sqlite +~~~~~~~~~~~~~~~~~~~~~~ + +1. Run the skyline_bootstrap container to bootstrap + + .. code:: bash + + rm -rf /tmp/skyline && mkdir /tmp/skyline + + docker run -d --name skyline_bootstrap -e KOLLA_BOOTSTRAP="" -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml -v /tmp/skyline:/tmp --net=host 99cloud/skyline:latest + + # Check bootstrap is normal `exit 0` + docker logs skyline_bootstrap + +2. Run the skyline service after bootstrap is complete + + .. code:: bash + + docker rm -f skyline_bootstrap + + .. + + If you need to modify skyline port, add + ``-e LISTEN_ADDRESS=`` in the following command + + ``LISTEN_ADDRESS`` defaults to ``0.0.0.0:9999`` + + .. code:: bash + + docker run -d --name skyline --restart=always -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml -v /tmp/skyline:/tmp --net=host 99cloud/skyline:latest + +Deployment with MariaDB +~~~~~~~~~~~~~~~~~~~~~~~ + +1. Connect to database of the OpenStack environment and create the + ``skyline`` database + + .. code:: 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. + + .. code:: 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 + + .. code:: 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. Run the skyline_bootstrap container to bootstrap + + .. code:: bash + + docker run -d --name skyline_bootstrap -e KOLLA_BOOTSTRAP="" -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host 99cloud/skyline:latest + + # Check bootstrap is normal `exit 0` + docker logs skyline_bootstrap + +5. Run the skyline service after bootstrap is complete + + .. code:: bash + + docker rm -f skyline_bootstrap + + .. + + If you need to modify skyline port, add + ``-e LISTEN_ADDRESS=`` in the following command + + ``LISTEN_ADDRESS`` defaults to ``0.0.0.0:9999`` + + .. code:: bash + + docker run -d --name skyline --restart=always -v /etc/skyline/skyline.yaml:/etc/skyline/skyline.yaml --net=host 99cloud/skyline:latest + +Test Access +~~~~~~~~~~~ + +You can now access the dashboard: ``https://:9999`` + +Develop Skyline-apiserver +------------------------- + +**Support Linux & Mac OS (Recommend Linux OS) (Because uvloop & cython)** + +Dependent tools +~~~~~~~~~~~~~~~ + + Use the new feature Context Variables of python37 & uvloop(0.15.0+ + requires python37). Considering that most systems do not support + python37, we choose to support python38 at least. + +- make >= 3.82 +- python >= 3.8 +- node >= 10.22.0 (Optional if you only develop with apiserver) +- yarn >= 1.22.4 (Optional if you only develop with apiserver) + +Install & Run +~~~~~~~~~~~~~ + +1. Installing dependency packages + + .. code:: bash + + tox -e venv + +2. Set skyline.yaml config file + + .. code:: 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: + + .. code:: yaml + + - database_url + - keystone_url + - default_region + - interface_type + - system_project_domain + - system_project + - system_user_domain + - system_user_name + - system_user_password + + .. + + If you set such as ``sqlite:////tmp/skyline.db`` for + ``database_url`` , just do as followed. If you set such as + ``mysql://root:root@localhost:3306/skyline`` for ``database_url`` + , you should refer to steps ``1`` and ``2`` of the chapter + ``Deployment with MariaDB`` at first. + +3. Init skyline database + + .. code:: bash + + source .tox/venv/bin/activate + make db_sync + deactivate + +4. Run skyline-apiserver + + .. code:: console + + $ source .tox/venv/bin/activate + $ uvicorn --reload --reload-dir 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. + + You can now access the online API documentation: + ``http://127.0.0.1:28000/docs``. + + Or, you can launch debugger with ``.vscode/lauch.json`` with vscode. + +5. Build Image + + .. code:: bash + + make build Devstack Integration -------------------- -Fast integration with `devstack <./devstack/README.rst>`__ to build an environment. +`Fast integration with Devstack to build an +environment. <./devstack/README.rst>`__ + +Kolla Ansible Deployment +------------------------ + +`Kolla Ansible to build an environment. <./kolla/README.md>`__ + +|image1| + +.. |image0| image:: doc/source/images/logo/OpenStack_Project_Skyline_horizontal.png +.. |image1| image:: doc/source/images/logo/nine-color-deer-64.png