Skip to main content
This guide walks you through setting up Ganimede for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.8 or higher
  • Node.js and npm
  • Git
  • pip (Python package installer)

​
Setup Process

1

Clone the repository

Clone the Ganimede repository to your local machine:
git clone https://github.com/nottherealsanta/ganimede.git
cd ganimede
2

Install API dependencies

Navigate to the api/ directory and install the package in editable mode:
cd api
pip install -e .
This will install all required dependencies including:
  • jupyter_client (7.4.9)
  • starlette (0.23.1)
  • ipykernel (6.20.2)
  • uvicorn (0.20.0)
  • websockets (11.0.3)
  • ypy-websocket (0.12.1)
  • And other dependencies
The -e flag installs the package in editable mode, allowing you to make changes to the code without reinstalling.
3

Install UI dependencies

Navigate to the ui/ directory and install the dependencies:
cd ../ui
npm ci
The npm ci command performs a clean install based on the package-lock.json file, ensuring consistent dependency versions.
4

Start the UI development server

In the ui/ directory, start the development server:
npm run dev
This starts both Vite and the Tailwind CSS watcher using concurrently. The UI will be available at the local development URL shown in the terminal.
5

Run the development server

In a new terminal, navigate to the api/ directory and start the Ganimede development server with a test notebook:
cd api
ganimede_dev tests/test4.ipynb
This launches Ganimede in development mode, connecting to your local UI development server.

​
Development Workflow

Once your environment is set up:
  1. UI Changes: The Vite dev server provides hot module replacement, so changes to Svelte components and styles will automatically reload in the browser
  2. API Changes: Since the API is installed in editable mode, Python changes take effect immediately. Restart ganimede_dev to apply changes to the server
  3. Testing: Use the test notebooks in the tests/ directory to verify your changes

​
Key Dependencies

​
Python (API)

jupyter_client==7.4.9
starlette==0.23.1
ipykernel==6.20.2
uvicorn==0.20.0
websockets==11.0.3
ypy-websocket==0.12.1

​
JavaScript (UI)

"svelte": "^3.59.2"
"vite": "^4.4.9"
"tailwindcss": "^3.3.3"

​
Troubleshooting

​
Port conflicts

If you encounter port conflicts, check that no other services are running on the default ports used by Vite and the Ganimede server.

​
WebSocket connection issues

Ensure both the UI dev server and ganimede_dev are running simultaneously for real-time collaboration features to work.

​
Python version issues

Ganimede requires Python 3.8 or higher. Verify your Python version: 
python3 --version

Build docs developers (and LLMs) love

Get started for freeTalk to us