Metadata-Version: 2.4
Name: jupyter-deploy
Version: 0.2.6
Summary: CLI based tool to deploy Jupyter applications that integrates with infrastructure as code frameworks.
Project-URL: Homepage, https://github.com/jupyter-infra/jupyter-deploy
Project-URL: github, https://github.com/jupyter-infra/jupyter-deploy/tree/main/libs/jupyter-deploy
Author-email: Jonathan Guinegagne <jggg@amazon.com>, Michael Chin <chnmch@amazon.com>, Brian Granger <brgrange@amazon.com>
License: MIT License
        
        Copyright (c) 2025 Amazon Web Services
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: click<8.2.0
Requires-Dist: decorator>=5.2.1
Requires-Dist: jupyter-core>=5.0.0
Requires-Dist: jupyter-deploy-tf-aws-ec2-base
Requires-Dist: packaging>=25.0
Requires-Dist: pydantic>=2.11.5
Requires-Dist: python-hcl2>=7.2.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.15.4
Requires-Dist: types-pyyaml>=6.0.12.20250516
Provides-Extra: aws
Requires-Dist: boto3-stubs>=1.38.23; extra == 'aws'
Requires-Dist: boto3>=1.38.23; extra == 'aws'
Requires-Dist: mypy-boto3-ec2>=1.40.4; extra == 'aws'
Requires-Dist: mypy-boto3-ssm>=1.38.5; extra == 'aws'
Description-Content-Type: text/markdown

# Jupyter Deploy

Jupyter deploy is an open-source command line interface tool (CLI) to deploy and manage
JupyterLab applications to remote compute instances provided by a Cloud provider.
Once deployed, you can access your application directly from your web browser,
and share its dedicated URL with collaborators. Collaborators may then work together
in real time on the same JupyterLab application.

## Templates
The `jupyter-deploy` CLI interacts with templates: infrastructure-as-code packages
that you can use to create your own project and deploy resources in your own cloud provider account.

Templates are nominally python packages distributed on `PyPI`. You can install and manage templates in your virtual
environment with `pip` or `uv`. The CLI automatically finds the templates installed in your Python environment.

The CLI ships with a default template: [jupyter-deploy-tf-aws-ec2-base](https://pypi.org/project/jupyter-deploy-tf-aws-ec2-base/).
Refer to `jupyter-deploy-tf-aws-ec2-base` on PyPI for instructions on setting up the AWS infrastructure needed for your deployment.

## Installation

Consider creating or activating a virtual environment.

### Install with pip

```bash
pip install jupyter-deploy
```

## The CLI

### Entry points
From a terminal, run:

```bash
jupyter-deploy --help

# or use the alias
jd --help

# or use the jupyter CLI
jupyter deploy --help
```


### Start a project
First create a new project directory:
```bash
mkdir my-jupyter-deployment
cd my-jupyter-deployment
```

In the rest of this page, we will use the default template.

```bash
# Get started with the default template
jupyter-deploy init .

# Or use the init flags to select another template that you installed in your virtual environment
jupyter-deploy init --help

# For example, the AWS EC2 base template
jupyter-deploy init -E terraform -P aws -I ec2 -T base . 
```

### Configure your project
There are two ways to configure your project:

---
**File based:**
Edit the `variables.yaml` file:
- add required variable values in the `required` and `required_sensitive` section
- optionally override default values in the `overrides` section 

Then run:
```bash
jupyter-deploy config
```

---
**Interactive experience:**
Alternatively, fill in the variable values from your terminal with:
```bash
# Discover the variables available for your specific template
jupyter-deploy config --help

# Run the interactive configuration and set the variables values as prompted
jupyter-deploy config

# Optionally save sensitive values to your project files
# Sensitive values are passwords, secret keys or API tokens that your applications
# need to access at runtime.
jupyter-deploy config -s

# Update a variable value afterwards (variable names depends on the template you use).
jupyter-deploy config --instance-type t3.small
```

### Deploy your project
The next step is to actually create your infrastructure
```bash
jupyter-deploy up
```

### Access your application
Once the project was successfully deployed, open your application in your web browser with:

```bash
jupyter-deploy open
```

You will be prompted to authenticate.
You can share this URL with collaborators, they will prompted to authenticate on their own web browser.

### Turn on and off your compute instance
The default template supports temporarily turning off your instance to reduce your cloud bill.

```bash
# Retrieve the current status of your compute instance
jupyter-deploy host status

# Stop an instance
jupyter-deploy host stop

# Restart it
jupyter-deploy host start

# You may also need to start the containers that run your application
jupyter-deploy server start
```

### Winddown your resources
To delete all the resources, run:

```bash
jupyter-deploy down
```

## License

The `jupyter-deploy` CLI is licensed under the [MIT License](LICENSE).