部署 Voilà#

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

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

设置示例项目#

创建一个您希望显示的笔记本的项目目录。在本教程中，我们将克隆 Voilà 并将笔记本文件夹作为我们的项目根目录。
```
git clone [email protected]: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 中，选择 URL 并使用 Voilà 端点：voila/render/path/to/notebook.ipynb
点击 Launch。
如果这是第一次启动（或者自上次构建以来有新的更改），Binder 将触发新的构建。这可能需要几分钟才能完成。如果图像已可用，服务器将在几秒钟内启动。

在 Binder 上自定义 Voilà#

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

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

可以在 voila-demo 存储库中找到示例。

在 Railway 上部署#

注意

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

Railway.app 是一个不错的选择，如果您想免费试用部署。您有有限的计算时间，但是如果应用程序处于空闲状态，它也会自动关闭。

从模板#

您可以直接点击此按钮，从可用模板创建自己的部署。这将创建一个 Github 模板的分支，您可以用自己的笔记本和依赖项填充它。

手动#

在 Railway 上部署的通用步骤可以在此处找到。以下是针对 Voilà 的高级指令。

按照官方文档的步骤在您的机器上安装 Railway CLI 并登录。
在项目目录中添加一个名为 runtime.txt 的文件，其中包含一个有效的 Python 运行时
```
python-3.10.4
```
如果您想显示所有笔记本，请在项目目录中添加一个名为 Procfile 的文件，内容如下：
```
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0
```
或者，如果您只想显示一个笔记本，请使用以下内容：
```
web: voila --port=$PORT --no-browser --Voila.ip=0.0.0.0 your_notebook.ipynb
```
初始化一个 git 仓库并提交您的代码。至少需要提交您的笔记本、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，而 WebSockets 是 Voilà 的必要条件。

在 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

如果您只想显示一个笔记本，请编辑最后一行。

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

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

在 Hugging Face Spaces 上部署#

您可以按照此处的说明将 Voilà 仪表板部署到 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 http://localhost: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 中创建一个新的 systemd 服务，用于运行 Voilà。该服务将确保 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 启动，以提供单个笔记本。您可以编辑命令以更改此行为以及 Voilà 提供的笔记本。

启用并启动 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 博客上的指南。

部署 Voilà#

设置示例项目#

云服务提供商#

在 Binder 上部署#

在 Binder 上自定义 Voilà#

在 Railway 上部署#

从模板#

手动#

在 Google App Engine 上部署#

在 Hugging Face Spaces 上部署#

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

先决条件#

步骤#

使用 Let’s Encrypt 启用 HTTPS#

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

设置 ngrok#

共享 Voilà 应用程序#