部署 Voilà#

部署文档分为两部分。首先是通用部分，应始终遵循。然后是针对特定云服务提供商的部分，应选择其中一个提供商。

如果您不确定在哪里部署您的应用，我们建议使用 Binder 或 Heroku。您可以测试部署和运行您的应用，而无需输入任何信用卡信息，并且几乎不需要任何部署经验。

设置一个示例项目#

为您希望展示的 notebook 创建一个项目目录。在本教程中，我们将克隆 Voilà 并将 notebooks 文件夹视为我们的项目根目录。
```
git clone git@github.com:voila-dashboards/voila.git
cd voila/notebooks/
```
在项目目录中添加一个 requirements.txt 文件。该文件应包含您的 Voilà 应用运行所需的所有 Python 依赖项。在本教程中，我们将复制 Voilà 的 environment.yml 文件的内容。我们省略了 xleaflet 和 xeus-cling，因为它们需要额外的工作，超出了本指南的范围。
```
bqplot
ipympl
ipyvolume
scipy
voila
```

云服务提供商#

在 Binder 上部署#

Binder 是部署 Voilà 应用程序最便捷的方式之一。该服务可在 mybinder.org 上找到，并越来越多地用于可复现研究，使其成为部署 Voilà 应用程序的绝佳选择。

确保仓库是公开可用的（在 GitHub、Gitlab 或作为 gist）。
按照本指南准备仓库。对于简单的部署，[设置一个示例项目]中列出的步骤就足够了。

注意

Binder 也支持 environment.yml 文件和 conda 环境。

转到 mybinder.org 并输入仓库的 URL。
在 Path to a notebook file（notebook文件路径）中，选择 URL 并使用 Voilà 端点：voila/render/path/to/notebook.ipynb
点击 Launch（启动）。
如果是首次启动（或自上次构建以来有新的更改），Binder 将触发一次新的构建。这可能需要几分钟才能完成。如果镜像已存在，服务器将在几秒钟内启动。

在 Binder 上自定义 Voilà#

要指定不同的选项（例如主题和模板），请在仓库的根目录下创建一个名为 jupyter_config.json 的文件，其内容如下

{
  "VoilaConfiguration": {
    "theme": "dark",
    "template": "gridstack"
  }
}

可以在 voila-demo 仓库中找到一个示例。

在 Ploomber Cloud 上部署#

Ploomber Cloud 为 Voilà 应用提供免费部署选项。创建帐户并登录后，请按照以下步骤操作

点击 “NEW” 按钮
在 “Framework” 部分，点击 Voilà
在 “Source code” 部分，点击 “Upload your files”
上传您的 .ipynb 文件和 requirements.txt 文件
点击 “CREATE”
等待部署完成。要查看您的应用，请点击 “VIEW” 按钮

部署 Voilà 应用的完整说明可在此处找到。

在 Railway 上部署#

注意

Heroku.com 曾是免费部署的推荐选项，但自2022年11月28日起，该平台已移除了免费产品计划。本节中描述的流程对其他服务仍然有效。

如果您想免费试用部署，Railway.app 是一个有吸引力的选择。您的计算时长有限，但如果应用空闲，它也会自动关闭。

从模板开始#

您只需按下此按钮，即可从可用模板创建您自己的部署。这将创建一个 Github 模板的分支，然后您可以用您的 Notebooks 和依赖项填充它。

手动操作#

在 Railway 上部署的一般步骤可以在这里找到。下面是针对 Voilà 的高级说明

遵循官方文档的步骤，在您的机器上安装 Railway CLI 并登录。
在项目目录中添加一个名为 runtime.txt 的文件，其中包含一个有效的 Python 运行时。
```
python-3.10.4
```
如果您想显示所有 notebooks，请在项目目录中添加一个名为 Procfile 的文件，其内容如下
```
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0
```
或者，如果您只想显示一个 notebook，则内容如下
```
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0 your_notebook.ipynb
```
初始化一个 git 仓库并提交您的代码。您至少需要提交您的 notebooks、requirements.txt、runtime.txt 和 Procfile。
```
git init
git add <your-files>
git commit -m "my message"
```
创建一个 Railway 实例并推送代码。
```
railway init
```
打开您的 web 应用
```
railway up --detach
```

为了解决问题，查看应用程序的日志很有用。您可以通过运行以下命令来做到这一点

railway up

在 Google App Engine 上部署#

您可以在Google App Engine的“灵活”环境中进行部署。这意味着底层机器将始终运行。这比“标准”环境更昂贵，后者类似于 Heroku 的免费选项。然而，Google App Engine 的“标准”环境不支持 websockets，而这是 voila 的一个要求。

在 Google App Engine 上部署的一般步骤可以在这里找到。下面是针对 Voilà 的高级说明

按照官方文档中的“开始之前”步骤创建您的帐户、项目和 App Engine 应用。

在项目目录中添加一个 app.yaml 文件，其内容如下

runtime: python
env: flex
runtime_config:
  python_version: 3
entrypoint: voila --port=$PORT --Voila.ip=0.0.0.0 --no-browser

如果您只想显示一个 notebook，请编辑最后一行

entrypoint: voila --port=$PORT --Voila.ip=0.0.0.0 --no-browser your_notebook.ipynb

部署您的应用
```
gcloud app deploy
```
打开您的应用
```
gcloud app browse
```

在 Hugging Face Spaces 上部署#

您可以按照这里的说明将 Voila 仪表板部署到 Hugging Face Spaces。

在私有服务器上运行 Voilà#

先决条件#

一台运行 Ubuntu 18.04（或更高版本）并具有 root 访问权限的服务器。
能够通过 SSH 连接到服务器并在提示符下运行命令。
服务器的公共 IP 地址。
一个指向服务器 IP 地址的域名。

步骤#

通过 SSH 连接到服务器
```
ssh ubuntu@<ip-address>
```
安装 nginx
```
sudo apt install nginx
```
要检查 nginx 是否已正确安装
```
sudo systemctl status nginx
```

创建文件 /etc/nginx/sites-enabled/yourdomain.com，内容如下

server {
    listen 80;
    server_name yourdomain.com;
    proxy_buffering off;
    location / {
        proxy_pass https://:8866;
        proxy_set_header Host $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 "upgrade";
        proxy_read_timeout 86400;
    }

    client_max_body_size 100M;
    error_log /var/log/nginx/error.log;
}

启用并启动 nginx 服务

sudo systemctl enable nginx.service
sudo systemctl start nginx.service

安装 pip

sudo apt update && sudo apt install python3-pip

按照[设置一个示例项目]中的说明操作，并安装依赖项
```
sudo python3 -m pip install -r requirements.txt
```

在 /usr/lib/systemd/system/voila.service 中为运行 Voilà 创建一个新的 systemd 服务。该服务将确保 Voilà 在启动时自动重启

[Unit]
Description=Voila

[Service]
Type=simple
PIDFile=/run/voila.pid
ExecStart=voila --no-browser voila/notebooks/basics.ipynb
User=ubuntu
WorkingDirectory=/home/ubuntu/
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

在此示例中，Voilà 通过 voila --no-browser voila/notebooks/basics.ipynb 启动，以提供单个 notebook。您可以编辑该命令以更改此行为以及 Voilà 提供的 notebooks。

启用并启动 voila 服务

sudo systemctl enable voila.service
sudo systemctl start voila.service

注意

要检查 Voilà 的日志

journalctl -u voila.service

现在访问 yourdomain.com 以访问 Voilà 应用程序。

使用 Let’s Encrypt 启用 HTTPS#

安装 certbot

sudo add-apt-repository ppa:certbot/certbot
sudo apt update
sudo apt install python-certbot-nginx

从 Let’s Encrypt 获取证书。 --nginx 标志将自动编辑 nginx 配置
```
sudo certbot --nginx -d yourdomain.com
```

/etc/nginx/sites-enabled/yourdomain.com 现在应包含更多条目

$ cat /etc/nginx/sites-enabled/yourdomain.com

...
listen 443 ssl; # managed by Certbot
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
...

访问 yourdomain.com 以通过 HTTPS 访问 Voilà 应用程序。
要自动续订证书（它们在 90 天后过期），请打开 crontab 文件
```
crontab -e
```
并添加以下行
```
0 12 * * * /usr/bin/certbot renew --quiet
```

有关更多信息，您也可以参考 nginx 博客上的指南。

使用 Apache2 作为反向代理#

Apache 也可以用来提供 voilà 服务。需要安装并启用以下 Apache 模块

mod_proxy
mod_rewrite
mod_proxy_http
mod_proxy_wstunnel

使用以下配置

<VirtualHost *:443>
   # ...
   ProxyRequests Off
   ProxyPreserveHost Off

   <LocationMatch  "/voila/">
      RewriteEngine on
      RewriteCond %{REQUEST_URI} /voila/api/kernels/
      RewriteRule .*/voila/(.*) "ws://127.0.0.1:50001/voila/$1" [P,L]
      ProxyPreserveHost On
      ProxyPass http://127.0.0.1:50001/voila/
      ProxyPassReverse  http://127.0.0.1:50001/voila/
   </LocationMatch>
</VirtualHost>

需要说明的是，Voila 是通过以下命令行实例化的

$ voila --autoreload=True --port=50001 --base_url=/voila/

客户端可以使用 https://myhost/voila/ 访问该实例

部署 Voilà#

设置一个示例项目#

云服务提供商#

在 Binder 上部署#

在 Binder 上自定义 Voilà#

在 Ploomber Cloud 上部署#

在 Railway 上部署#

从模板开始#

手动操作#

在 Google App Engine 上部署#

在 Hugging Face Spaces 上部署#

在私有服务器上运行 Voilà#

先决条件#

步骤#

使用 Let’s Encrypt 启用 HTTPS#

使用 Apache2 作为反向代理#

使用 ngrok 共享 Voilà 应用程序#

设置 ngrok#

共享 Voilà 应用程序#