Upgrading to JupyterHub version 0.8¶
This document will assist you in upgrading an existing JupyterHub deployment from version 0.7 to version 0.8.
Upgrade checklist¶
- Review the release notes. Review any deprecated features and pay attention to any backwards incompatible changes
- Backup JupyterHub database:
jupyterhub.sqlite
when using the default sqlite database- Your JupyterHub database when using an RDBMS
- Backup the existing JupyterHub configuration file:
jupyterhub_config.py
- Shutdown the Hub
- Upgrade JupyterHub
pip install -U jupyterhub
when usingpip
conda upgrade jupyterhub
when usingconda
- Upgrade the database using run
`jupyterhub upgrade-db
- Update the JupyterHub configuration file
jupyterhub_config.py
Backup JupyterHub database¶
To prevent unintended loss of data or configuration information, you should back up the JupyterHub database (the default SQLite database or a RDBMS database using PostgreSQL, MySQL, or others supported by SQLAlchemy):
- If using the default SQLite database, back up the
jupyterhub.sqlite
database. - If using an RDBMS database such as PostgreSQL, MySQL, or other supported by SQLAlchemy, back up the JupyterHub database.
Note
Losing the Hub database is often not a big deal. Information that resides only in the Hub database includes:
- active login tokens (user cookies, service tokens)
- users added via GitHub UI, instead of config files
- info about running servers
If the following conditions are true, you should be fine clearing the Hub database and starting over:
- users specified in config file
- user servers are stopped during upgrade
- don’t mind causing users to login again after upgrade
Backup JupyterHub configuration file¶
Backup up your configuration file, jupyterhub_config.py
, to a secure
location.
Shutdown JupyterHub¶
- Prior to shutting down JupyterHub, you should notify the Hub users of the scheduled downtime.
- Shutdown the JupyterHub service.
Upgrade JupyterHub¶
Follow directions that correspond to your package manager, pip
or conda
,
for the new JupyterHub release:
pip install -U jupyterhub
forpip
conda upgrade jupyterhub
forconda
Upgrade the proxy, authenticator, or spawner if needed.
Upgrade JupyterHub database¶
To run the upgrade process for JupyterHub databases, enter:
jupyterhub upgrade-db
Update the JupyterHub configuration file¶
Create a new JupyterHub configuration file or edit a copy of the existing
file jupyterhub_config.py
.
Start JupyterHub¶
Start JupyterHub with the same command that you used before the upgrade.