Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aminnez/jupyterbook
A comprehensive Jupyter notebook environment with multi-user support through JupyterHub, supporting both Python and Java programming via the IJava kernel.
https://github.com/aminnez/jupyterbook
docker docker-compose ijava jupyter jupyter-notebook jupyterhub jupyterlab
Last synced: about 1 month ago
JSON representation
A comprehensive Jupyter notebook environment with multi-user support through JupyterHub, supporting both Python and Java programming via the IJava kernel.
- Host: GitHub
- URL: https://github.com/aminnez/jupyterbook
- Owner: aminnez
- License: mit
- Created: 2025-01-20T07:33:41.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-01-20T10:50:57.000Z (about 1 month ago)
- Last Synced: 2025-01-20T11:30:06.068Z (about 1 month ago)
- Topics: docker, docker-compose, ijava, jupyter, jupyter-notebook, jupyterhub, jupyterlab
- Language: Dockerfile
- Homepage:
- Size: 14.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# JupyterHub+JupyterLab+IJava
## Overview
A comprehensive [Jupyter](https://jupyter.org/) notebook environment with support for both Java and Python, featuring [JupyterHub](https://github.com/jupyterhub/jupyterhub) for user authentication.
- [JupyterHub](https://github.com/jupyterhub/jupyterhub) as the core platform for multi-user support.
- [Jupyter](https://jupyter.org/) and [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) as the primary interfaces.
- Java programming via the [IJava](https://github.com/SpencerPark/IJava) kernel.
- User authentication via [Google OAuth](https://developers.google.com/identity/protocols/oauth2).
## Prerequisites
Ensure you have the following installed before starting:
- Docker (version 20.10 or later)
- Docker Compose (version 1.29 or later)
- Git (optional, for cloning the repository)
## Project Structure
```txt
├── Dockerfile # Container build instructions
├── docker-compose.yml # Docker Compose configuration
├── nginx.conf # Nginx reverse proxy configuration
├── jupyterhub_config.py # JupyterHub configuration
├── data # Data volumes to persist data
└── ssl # SSL certificates
```
## Quick Start
### 1. Clone the Repository
```bash
git clone https://github.com/aminnez/jupyterbook.git
cd jupyterbook
```
### 2. Configure Nginx
- **Replace** `example.com` with your desired domain in `nginx.conf`.
- **Generate SSL** certificates for the Nginx reverse proxy and place `fullchain.pem` and `privkey.pem` in the `ssl` directory.
### 3. Build and Start the Environment
```bash
# Build and start the containers in detached mode
docker compose up -d
# View running containers
docker compose ps
```
### 4. Access JupyterBook
- **URL:** `https://example.com`
- **Supported Languages:**
- Python (default)
- Java (via IJava kernel)
## Configuration
### Google OAuth Configuration
1. **Create Google OAuth Credentials:**
- Go to the [Google Cloud Console](https://console.cloud.google.com/)
- Create a new project or select an existing project
- Navigate to `APIs & Services` > `Credentials`
- Click `Create Credentials` > `OAuth client ID`
- Choose `Web application` as the application type
- Add your domain (e.g., `https://example.com`) to the Authorized JavaScript origins
- Add `https://example.com/hub/oauth_callback` to the Authorized redirect URIs
- Save the client ID and client secret
2. **Set Environment Variables:**
Create a `.env` file in the project root with your Google OAuth credentials:
```bash
GOOGLE_OAUTH_CLIENT_ID=your_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_client_secret
OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback
```
3. **User Restrictions:**
- Uncomment and modify the `admin_users` and `allowed_users` lines in `jupyterhub_config.py` to restrict access to specific users.
### Port Configuration
To change the port, update the `docker-compose.yml` file as necessary.
## Development Workflow
1. Make changes to project files.
2. Rebuild the container:
```bash
docker compose down
docker compose up -d --build
```
## Troubleshooting
- **Permission Errors:** Run with `sudo` if encountering permission problems.
- **Container Logs:**
```bash
docker compose logs
```
## Security Considerations
- Change default authentication methods.
- Use environment variables for sensitive configurations.
- Regularly update base images and dependencies.
## Contributing
1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a Pull Request.
## License
This project is licensed under the MIT License.
Copyright (c) 2025 Amin Nezampour
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, 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.
See the [LICENSE.md](LICENSE.md) file for complete license details.
## Contact
[aminnez.com](https://aminnez.com)