Ambuda

<div align="center"> <h1>Ambuda</h1> <p><i>A breakthrough Sanskrit library</i></p> </div>

Ambuda is an online Sanskrit library. This repository contains Ambuda's core code, and this README will show you how to build and change it.

Contents

• Quickstart
• Architecture
• Documentation
• Contributing

Quickstart

This quickstart will show you how to:

• start Ambuda with Docker
• create an admin user
• upload content to the site

Starting Ambuda with Docker

The quickest way to run Ambuda on your computer is to use docker compose from your command line.

[!TIP] You can install docker compose through either the Docker website or your favorite package manager. If you have a Unix machine and don't like Docker Desktop, we recommend Colima.

Once you have docker configured, starting the site is simple:

make ambuda-dev

The make ambuda-dev command will do the following:

• Build an Ambuda Docker image. This will likely take a few minutes the first time it runs, but it will be substantially faster on subsequent runs.

• Start Ambuda's main services: the web server, a Celery pool for background tasks, and Redis for Celery interop.

• Initialize a Sqlite database with sample data. Data is persisted to the data/ directory and survives across restarts.

• Set up hot reloading for Python, CSS, and JavaScript.

• Start the web server at http://localhost:5000.

To quit, press Ctrl+C to stop all services.

[!TIP]

If you ever run into build issues with make ambuda-dev, first run make ambuda-dev-build then try again.

[!WARNING]

Run CLI commansd within make ambuda-dev-shell.

Creating an admin user

Once the Docker service is up, create an admin user so that you can log in:

make ambuda-dev-shell

# Inside the shell

# This command creates a new user.
> uv run cli.py create-user

# This command assigns the `admin` role to your new user.
> uv run cli.py add-role --username <your-username> --role admin

After you've created your admin user, go to http://localhost:5000/sign-in to sign in.

Creating test data

(Under revision.)

Use create-toy-data to create a toy project.

make ambuda-dev-shell

# Inside the shell
> uv run cli.py create-toy-data

Uploading content to the site

(Under revision.)

Once you've logged in as an admin user go to https://localhost:5000/admin/ to open the Admin UI.

Documentation

Our docs contain information about our tech stack, architecture, design decisions, and so on. To read them, see the docs folder, or build them from scratch and open them in your browser:

$ make docs
$ open docs/_build/html/index.html

Troubleshooting

• table already exists
  • Run make ambuda-dev-shell then uv run alembic upgrade head`.
  • If problems persist, delete the local database and try again.

Contributing

For details on how to contribute to Ambuda, see CONTRIBUTING.md. We also strongly recommend joining our mailing list, where we have an ongoing informal discussion about Ambuda's technical problems and roadmap.