Skip to content

update deployment documentation #1277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 1, 2023
Merged

update deployment documentation #1277

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8abae62
describe how to use railway instead of heroku
12rambau Jan 11, 2023
26b1cb4
use voila palette for documentation
12rambau Jan 11, 2023
ceb3c22
indentation issue in docs
12rambau Jan 11, 2023
e4d3d12
Merge branch 'main' into deployment
martinRenou Aug 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/source/_static/main_stylesheet.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,12 @@
.wy-nav-content img {
margin: 5px auto 25px;
}

/*use voila palette for title coloring*/
html[data-theme="light"] {
--pst-color-primary: #5dbcaf;
}

html[data-theme="dark"] {
--pst-color-primary: #5dbcaf;
}
204 changes: 105 additions & 99 deletions docs/source/deploy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,41 +81,48 @@ Customizing Voilà on Binder
To specify different options (such as the theme and template), create a
``jupyter_config.json`` file at the root of the repository with the following content:

.. code:: json
.. code:: json

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


An example can be found in the
`voila-demo <https://github.com/maartenbreddels/voila-demo>`__ repository.


Deployment on Heroku
--------------------
Deployment on Railway
---------------------

.. note::

Heroku.com is an attractive option if you want to try out deployment for
free. You have limited computing hours, however the app will also
automatically shutdown if it is idle.
Heroku.com was the suggested option for free deployment but since `November 28th 2022 <https://help.heroku.com/RSBRUH58/removal-of-heroku-free-product-plans-faq>`__, free
product plans have been removed from the platform. The process described in
this section remain valid for other services.

The general steps for deployment at Heroku can be found
`here <https://devcenter.heroku.com/articles/getting-started-with-python>`__.
`Railway.app <https://railway.app>`__ is an attractive option if you want to try
out deployment for free. You have limited computing hours, however the app will
also automatically shutdown if it is idle.

The general steps for deployment at Railway can be found
`here <https://nixpacks.com/docs/providers/python>`__.
High level instructions, specific to Voilà can be found below:

1. Follow the steps of the official documentation to install the heroku
cli and login on your machine.
1. Follow the steps of the official documentation to install the Railway
CLI and login on your machine.

2. Add a file named runtime.txt to the project directory with a
`valid Python runtime <https://devcenter.heroku.com/articles/python-support#supported-runtimes>`__:

.. code:: text

python-3.10.4

3. Add a file named Procfile to the project directory with the
3. Add a file named ``Procfile`` to the project directory with the
following content if you want to show all notebooks:

.. code:: text
Expand All @@ -128,7 +135,7 @@ High level instructions, specific to Voilà can be found below:

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

4. Initialize your git repo and commit your code. At minimum you need to commit
4. Initialize a git repo and commit your code. At minimum you need to commit
your notebooks, requirements.txt, runtime.txt, and the Procfile.

.. code:: bash
Expand All @@ -137,24 +144,23 @@ High level instructions, specific to Voilà can be found below:
git add <your-files>
git commit -m "my message"

5. Create an Heroku instance and push the code.
5. Create an Railway instance and push the code.

.. code:: bash

heroku create
git push heroku master
railway init

6. Open your web app

.. code:: bash

heroku open
railway up --detach

To resolve issues, it is useful to see the logs of your application. You can do this by running:

.. code:: bash
.. code:: bash

heroku logs --tail
railway up


Deployment on Google App Engine
Expand Down Expand Up @@ -218,96 +224,96 @@ Steps

1. SSH into the server:

.. code:: text
.. code:: text

ssh ubuntu@<ip-address>
ssh ubuntu@<ip-address>

2. Install nginx:

.. code:: text
.. code:: text

sudo apt install nginx
sudo apt install nginx

3. To check that ``nginx`` is correctly installed:

.. code:: text
.. code:: text

sudo systemctl status nginx
sudo systemctl status nginx

4. Create the file ``/etc/nginx/sites-enabled/yourdomain.com`` with the following content:

.. code:: text
.. code:: text

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;
}
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;
}

5. Enable and start the ``nginx`` service:

.. code:: text
.. code:: text

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

6. Install pip:

.. code:: text
.. code:: text

sudo apt update && sudo apt install python3-pip
sudo apt update && sudo apt install python3-pip

7. Follow the instructions in `Setup an example project`_, and install the dependencies:

.. code:: text

sudo python3 -m pip install -r requirements.txt

8. Create a new systemd service for running Voilà in ``/usr/lib/systemd/system/voila.service``.
The service will ensure Voilà is automatically restarted on startup:
.. code:: text

.. code:: text
sudo python3 -m pip install -r requirements.txt

[Unit]
Description=Voila
8. Create a new systemd service for running Voilà in ``/usr/lib/systemd/system/voila.service``. The service will ensure Voilà is automatically restarted on startup:

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

[Install]
WantedBy=multi-user.target
[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

In this example Voilà is started with ``voila --no-browser voila/notebooks/basics.ipynb`` to serve a single notebook.
You can edit the command to change this behavior and the notebooks Voilà is serving.

9. Enable and start the ``voila`` service:

.. code:: text
.. code:: text

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

.. note::

To check the logs for Voilà:

.. code:: text
Expand All @@ -322,45 +328,45 @@ Enable HTTPS with Let's Encrypt

1. Install ``certbot``:

.. code:: text
.. code:: text

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

2. Obtain the certificates from Let's Encrypt. The ``--nginx`` flag will edit the nginx configuration automatically:

.. code:: text

sudo certbot --nginx -d yourdomain.com
.. code:: text
sudo certbot --nginx -d yourdomain.com

3. ``/etc/nginx/sites-enabled/yourdomain.com`` should now contain a few more entries:

.. code :: text

$ cat /etc/nginx/sites-enabled/yourdomain.com
.. code :: text

...
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
...
$ 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
...

4. Visit ``yourdomain.com`` to access the Voilà applications over HTTPS.

5. To automatically renew the certificates (they expire after 90 days), open the ``crontab`` file:

.. code :: text
.. code :: text

crontab -e
crontab -e

And add the following line:
And add the following line:

.. code :: text
.. code :: text

0 12 * * * /usr/bin/certbot renew --quiet
0 12 * * * /usr/bin/certbot renew --quiet

For more information, you can also follow `the guide on the nginx blog <https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/>`__.

Expand Down