为开发者安装和运行¶

StoryBoard 主要有两个组件：API 服务器和基于 Javascript 的 Web 客户端。API 服务器是必需的，但如果存在替代方案，Web 客户端也可以被替换。这意味着可以使用不同的用户界面与 StoryBoard API 交互；这些替代方案的安装说明在其各自的仓库中有详细介绍（例如，boartty，一个命令行界面，可以在这里找到：https://git.openstack.org/cgit/openstack/boartty/）。

本安装指南将涵盖 API 和最广泛使用的 StoryBoard Web 客户端，并假定在 Ubuntu 16.04 或更新版本上运行。这些说明对于其他发行版也基本适用。

设置您的机器以开发 StoryBoard 的推荐方法是使用提供的 docker-compose.yml 文件。但是，如果您愿意，我们也提供了手动设置的说明。

使用 Docker¶

此方法使用 Docker 运行 StoryBoard 所需的服务，例如 MySQL 和 RabbitMQ。StoryBoard API 和 Web 客户端直接在主机上运行，以缩短开发周期。它们使用 tox 在虚拟环境中运行，以最大程度地减少所需的手动安装量。

完成这些步骤后，您应该可以在 https://:8080/ 上运行可用的 StoryBoard API，并在 https://:9000/ 上访问可用的 StoryBoard Web 客户端。

1. 安装 Docker¶

请遵循您平台的 Docker 安装说明。

注意

在 Linux 上，请务必将您的用户添加到 docker 组，以避免需要 sudo。

sudo usermod -aG docker your-user

您需要注销并重新登录才能使此设置生效。

2. 安装 docker-compose¶

可以使用 pip 安装

pip3 install --user docker-compose

或者遵循您平台的安装说明。

3. 获取代码¶

代码使用 git 存储，因此您需要安装 git。

sudo apt install git

然后可以克隆 API 和 Web 客户端的代码。

git clone https://git.openstack.org/openstack-infra/storyboard
git clone https://git.openstack.org/openstack-infra/storyboard-webclient
cd storyboard

4. 运行容器¶

目前，docker-compose.yml 文件设置了 3 个容器来提供以下服务：

MySQL
Swift
RabbitMQ

您可以通过在 storyboard 仓库的根目录下执行以下命令来启动容器。

cd docker
docker-compose up

注意

您可以通过执行以下操作使 docker-compose 进程在后台运行：

cd docker
docker-compose up -d

5. 安装依赖项¶

运行 API 和构建 Web 客户端需要一些依赖项。在 Ubuntu 上，您可以使用以下命令安装它们：

sudo apt install build-essential python3-dev
pip3 install --user tox

6. 迁移数据库¶

此时您可以运行 StoryBoard，但由于数据库为空，它毫无用处。迁移使用 storyboard-db-manage 脚本运行，您可以在 storyboard 仓库的根目录下使用 tox 运行它。

tox -e venv -- storyboard-db-manage --config-file ./docker/storyboard.conf upgrade head

此命令按顺序运行所有数据库迁移。它底层使用 alembic，并具有类似的 CLI。

7. 运行 API¶

API 使用 storyboard-api 命令运行。同样，您可以在 storyboard 仓库的根目录下使用 tox 运行它。

tox -e venv -- storyboard-api --config-file ./docker/storyboard.conf

docker/storyboard.conf 配置文件包含已设置为使用先前创建的容器的配置，因此无需手动配置。

此命令的输出应以类似以下内容结束：

2019-03-20 11:25:44.862 22047 INFO storyboard.api.app [-] Starting server in PID 22047
2019-03-20 11:25:44.863 22047 INFO storyboard.api.app [-] Configuration:
2019-03-20 11:25:44.863 22047 INFO storyboard.api.app [-] serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

此时，API 正在成功运行。您可以使用 Ctrl+C 或关闭终端来停止它。

8. 运行 Web 客户端¶

storyboard-webclient 仓库提供了一个 tox 目标，该目标构建 Web 客户端并使用开发服务器对其进行服务。您可以在 storyboard-webclient 仓库的根目录下使用 tox 运行它。

tox -e grunt_no_api -- serve

这需要一些时间才能运行，因为它使用 npm 获取所需的依赖项，并构建 node-sass。

此命令的输出应以类似以下内容结束：

Running "connect:livereload" (connect) task
Started connect web server on http://localhost:9000

Running "watch" task
Waiting...

此时 Web 客户端正在成功运行。您可以使用 Ctrl+C 或关闭终端来停止它。对代码库中现有文件的任何更改都会导致它自动重新构建 Web 客户端并刷新浏览器中的页面，以帮助简化开发工作流程。

您可以在浏览器中访问 https://:9000/ 查看它。您应该也可以在此处登录。提供的配置文件使用 Ubuntu One 作为 OpenID 提供商，因此您需要一个 Ubuntu One 帐户才能这样做。

9. 启用通知¶

StoryBoard 中的通知由订阅消息队列事件的工作人员处理。目前仅支持 RabbitMQ。docker-compose.yml 文件运行一个 RabbitMQ 服务器，并且提供的配置文件已设置为启用通知。

要运行工作人员以便实际创建通知，请在 storyboard 仓库的根目录下使用 tox。

tox -e venv -- storyboard-worker-daemon --config-file ./docker/storyboard.conf

这将启动 5 个工作人员来监听事件并创建任何相关通知。

手动安装¶

1. 安装依赖项¶

要启动 API 服务器，请确保您在本地安装了以下软件包：

build-essential
python3-dev
python3-pip

MySQL

sudo apt update
sudo apt install build-essential python3-dev python3-pip
sudo apt install mysql-server-5.7    # Here you should be asked to set a password
mysql --version

注意

MySQL 必须 >= 5.6，以支持 InnoDB 表上的全文索引。

警告

在 Ubuntu 17.10 或更新版本上，mysql 不会要求设置 root 密码。您需要手动设置一个，可以在这里阅读如何操作。

2. 获取代码¶

代码使用 git 存储，因此您需要安装 git。

sudo apt install git

然后可以克隆 API 和 Web 客户端的代码。

git clone https://git.openstack.org/openstack-infra/storyboard
git clone https://git.openstack.org/openstack-infra/storyboard-webclient
cd storyboard

3. 创建数据库¶

StoryBoard 需要一个数据库。这些命令创建一个名为 storyboard 的数据库，并删除任何同名的现有数据库。

mysql -u root -p -e 'DROP DATABASE IF EXISTS storyboard;'
mysql -u root -p -e 'CREATE DATABASE storyboard;'

注意

如果您想使用非 root 用户，请将 root 更改为您所需的用户名。

4. 创建配置文件¶

StoryBoard 需要一个配置文件才能运行。除示例内容外，最小可用配置还需要包含一个未注释的 connection 行，以便允许数据库连接。

cp ./etc/storyboard.conf.sample ./etc/storyboard.conf

要将其转换为可用的配置文件，需要进行一些更改。编辑 ./etc/storyboard.conf 并进行以下更改：

在 database 部分中，更新 connection 行，将 root:pass 替换为您连接数据库时使用的用户名和密码。这很可能是 root 以及您在安装 MySQL 时选择的密码。

通过删除 # 来取消注释此行，确保行开头没有空格。

警告

如果您在 VM 中运行 API，并计划远程访问它（即通过其 IP 地址或主机名），您还需要将该 IP 地址或主机名添加到 oauth 部分中的 valid_oauth_clients 行。也取消注释此行。如果以 ^ 字符开头，它也可以是正则表达式。

5. 安装 tox¶

StoryBoard 使用 tox 来运行测试和管理用于运行开发服务器的虚拟环境。

pip3 install --user tox

注意

如果这是您第一次将 --user 传递给 pip，您可能需要将 ~/.local/bin 添加到您的 PATH。

6. 迁移数据库¶

tox -e venv -- storyboard-db-manage --config-file ./etc/storyboard.conf upgrade head

此命令按顺序运行所有数据库迁移。它底层使用 alembic，并具有类似的 CLI。

7. 运行 API¶

API 使用 storyboard-api 命令运行。同样，您可以在 storyboard 仓库的根目录下使用 tox 运行它。

tox -e venv -- storyboard-api --config-file ./etc/storyboard.conf

此命令的输出应以类似以下内容结束：

2019-03-20 11:25:44.862 22047 INFO storyboard.api.app [-] Starting server in PID 22047
2019-03-20 11:25:44.863 22047 INFO storyboard.api.app [-] Configuration:
2019-03-20 11:25:44.863 22047 INFO storyboard.api.app [-] serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

此时，API 正在成功运行。您可以使用 Ctrl+C 或关闭终端来停止它。

8. 运行 Web 客户端¶

tox -e grunt_no_api -- serve

这需要一些时间才能运行，因为它使用 npm 获取所需的依赖项，并构建 node-sass。

此命令的输出应以类似以下内容结束：

Running "connect:livereload" (connect) task
Started connect web server on http://localhost:9000

Running "watch" task
Waiting...

可选：启用通知¶

StoryBoard 中的通知由订阅消息队列事件的工作人员处理。目前仅支持 RabbitMQ。

1. 在您的开发机器上安装 RabbitMQ¶

启用通知的第一步是在您的开发实例上安装 RabbitMQ。

sudo apt install rabbitmq-server

2. 设置 RabbitMQ¶

为 StoryBoard 创建一个 rabbitmq 用户/密码（有关更多信息，请参阅 rabbitmq manpages）。

#                         (username) (password)
sudo rabbitmqctl add_user storyboard storyboard
sudo rabbitmqctl set_permissions -p / storyboard ".*" ".*" ".*"

3. 配置通知¶

StoryBoard 需要在其配置文件中设置各种键，以了解如何使用 RabbitMQ，并且需要显式启用通知功能。

在您的 storyboard.conf 文件中设置以下配置，如果上一步中使用了不同的用户 ID 和密码，请相应地替换它们。

[DEFAULT]
enable_notifications = True

[notifications]
rabbit_host=127.0.0.1
rabbit_login_method = AMQPLAIN
rabbit_userid = storyboard
rabbit_password = storyboard
rabbit_port = 5672
rabbit_virtual_host = /

4. 重启 API¶

如果 API 正在运行，请立即重新启动以应用配置更改。使用 Ctrl+C 停止现有进程，并再次在 storyboard 仓库的根目录下使用 tox。

tox -e venv -- storyboard-api --config-file ./etc/storyboard.conf

5. 运行工作程序¶

要运行工作人员以便实际创建通知，请在 storyboard 仓库的根目录下使用 tox。

tox -e venv -- storyboard-worker-daemon --config-file ./etc/storyboard.conf

这将启动 5 个工作人员来监听事件并创建任何相关通知。

使用您的开发 StoryBoard¶

一旦 API 和 Web 客户端开发服务器运行，您可以通过几种方式使用您的开发实例 StoryBoard。

默认情况下，Web 客户端开发服务器使用端口 9000，因此可以通过在同一台机器上运行的 Web 浏览器中导航到 https://:9000/ 来访问它。

如果您的浏览器在不同的机器上，则运行 API 的机器的主机名或 IP 地址必须在 API 的 ./etc/storyboard.conf 文件中的 valid_oauth_clients 键中，以便进行登录。如果以 ^ 字符开头，它也可以是正则表达式。

默认情况下，API 服务器使用端口 8080，因此可以在 https://:8080/ 访问 API。这将产生 404，因为 API 在 / 端点上实际上不提供任何内容，但这反直觉地意味着它可能正在工作。可用的 API 端点在 V1 Web API 页面上有文档记录。

Web 客户端服务器还将 /api 转发到 API 服务器，因此也可以通过将请求发送到 https://:9000/api/ 来使用 API。

可选步骤：使用基本数据填充数据库¶

如果您想在数据库中定义超级用户，请将 ./etc/superusers.yaml.sample 复制到 ./etc/superusers.yaml 并定义一些超级用户 ID。

在数据库中启用超级用户。

tox -e venv -- storyboard-db-manage --config-file ./etc/storyboard.conf load_superusers ./etc/superusers.yaml

如果您想快速在数据库中设置一组项目和项目组，请将 ./etc/projects.yaml.sample 复制到 ./etc/projects.yaml 并定义一些项目和项目组。

在数据库中创建项目和项目组。

tox -e venv -- storyboard-db-manage --config-file ./etc/storyboard.conf load_projects ./etc/projects.yaml

为开发者安装和运行

为开发者安装和运行¶

使用 Docker¶

1. 安装 Docker¶

2. 安装 docker-compose¶

3. 获取代码¶

4. 运行容器¶

5. 安装依赖项¶

6. 迁移数据库¶

7. 运行 API¶

8. 运行 Web 客户端¶

9. 启用通知¶

手动安装¶

1. 安装依赖项¶

2. 获取代码¶

3. 创建数据库¶

4. 创建配置文件¶

5. 安装 tox¶

6. 迁移数据库¶

7. 运行 API¶

8. 运行 Web 客户端¶

可选：启用通知¶

1. 在您的开发机器上安装 RabbitMQ¶

2. 设置 RabbitMQ¶

3. 配置通知¶

4. 重启 API¶

5. 运行工作程序¶

使用您的开发 StoryBoard¶

可选步骤：使用基本数据填充数据库¶

storyboard-api 1.1.1.dev8

页面内容