You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airavata.apache.org by ya...@apache.org on 2026/04/08 07:02:24 UTC
(airavata-portals) 14/21: docs: update README for modernized portal stack
This is an automated email from the ASF dual-hosted git repository.
yasith pushed a commit to branch feat/sdk-facade-migration
in repository https://gitbox.apache.org/repos/asf/airavata-portals.git
commit a2a548671c00c13c4c007565cc6b1354944c81c3
Author: yasithdev <ya...@icloud.com>
AuthorDate: Wed Apr 8 00:56:54 2026 -0500
docs: update README for modernized portal stack
---
airavata-django-portal/README.md | 221 ++++++++++++---------------------------
1 file changed, 66 insertions(+), 155 deletions(-)
diff --git a/airavata-django-portal/README.md b/airavata-django-portal/README.md
index 491543ad5..255b12d52 100644
--- a/airavata-django-portal/README.md
+++ b/airavata-django-portal/README.md
@@ -1,199 +1,110 @@
# Apache Airavata Django Portal
-
-[](https://apache-airavata-django-portal.readthedocs.io/en/latest/?badge=latest)
+Web portal for Apache Airavata, providing a user interface for managing experiments, applications, and compute resources.
-The Airavata Django Portal is a web interface to the
-[Apache Airavata](http://airavata.apache.org/) API implemented using the Django
-web framework. The intention is that the Airavata Django Portal can be used as
-is for a full featured web based science gateway but it can also be customized
-through various plugins to add more domain specific functionality as needed.
+## Tech Stack
-## Getting Started
+- **Backend:** Python 3.12+, Django 5.1, Django REST Framework
+- **Frontend:** Vue 3, Vite, Bootstrap 5
+- **CMS:** Wagtail 6
+- **API Client:** airavata-python-sdk (gRPC)
-The following steps will help you quickly get started with running the Airavata
-Django Portal locally. This will allow you to try it out and can also be used as
-a development environment. If you just want to run the Airavata Django Portal
-locally, see the Docker instructions below for a more simplified approach.
+## Prerequisites
-The Airavata Django Portal works with Python versions 3.6 - 3.10. You'll need
-one of these versions installed locally.
+| Requirement | Version |
+|-------------|---------|
+| Python | 3.12+ |
+| Node.js | 22+ |
+| Yarn | 1.22+ |
+| Docker | 20.10+ |
+| Tilt | 0.33+ |
-You'll also need Node.js and yarn to build the JavaScript frontend code. Please
-install Node.js version 19. You
-can also use [nvm](https://github.com/nvm-sh/nvm) to manage the Node.js install.
-If you have nvm installed you can run `nvm install && nvm use` before running
-any yarn commands. See
-[the Yarn package manager](https://classic.yarnpkg.com/lang/en/) for information
-on how to install Yarn 1 (Classic).
+## Quick Start
-1. Checkout this project and create a virtual environment.
-
- ```
- git clone https://github.com/apache/airavata-django-portal.git
- cd airavata-django-portal
- python3 -m venv venv
- source venv/bin/activate
- pip install --upgrade pip setuptools wheel
- pip install -r requirements.txt
- ```
-
- - **Windows note**: Use ```venv\Scripts\activate``` instead of ```source venv/bin/activate```
- <!-- https://docs.python.org/3/library/venv.html -->
-
- - **macOS note**: to install the MySQL dependencies you need to have the
- MySQL development headers and libraries installed. Also, on macOS you need
- to have openssl installed. See the
- [mysqlclient-python installation notes](https://github.com/PyMySQL/mysqlclient-python#install)
- for more details.
-
-2. Create a local settings file.
-
- - Option 1 (**recommended**). The best way to get a local settings file is
- to download one from an existing Airavata Django Portal instance. If you
- have Admin access, you can log in, go to _Settings_ and then _Developer
- Console_ (/admin/developers) and download a `settings_local.py` file for
- local development. Save it to the `django_airavata/` directory.
-
- - Option 2. Otherwise, if you know the hostname and ports of an Airavata
- deployment, you can copy `django_airavata/settings_local.py.sample` to
- `django_airavata/settings_local.py` and edit the contents to match your
- Keycloak and Airavata server deployments.
-
- ```
- cp django_airavata/settings_local.py.sample django_airavata/settings_local.py
- ```
-
-3. Run Django migrations
-
- ```
- python manage.py migrate
- ```
-
-4. Build the JavaScript sources. There are a few JavaScript packages in the
- source tree, colocated with the Django apps in which they are used. The
- `build_js.sh` script will build them all.
-
- ```
- ./build_js.sh
- ```
-
- - **Window note**: on Windows, run `.\build_js.bat` instead
-
-5. Load the default Wagtail CMS pages.
-
- ```
- python manage.py load_cms_data new_default_theme
- ```
+```bash
+tilt up
+```
-6. Run the server
+This starts MariaDB, the Django dev server (port 8000), and frontend dev servers with HMR.
- ```
- python manage.py runserver
- ```
+## Manual Setup
-7. Point your browser to http://localhost:8000.
+```bash
+# Infrastructure
+docker compose -f compose/docker-compose.yaml up -d
-## Docker instructions
+# Backend
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+python manage.py migrate
+python manage.py runserver
-To run the Django Portal as a Docker container, you need a `settings_local.py`
-file which you can create from the `settings_local.py.sample` file. Then run the
-following:
+# Frontend (per app)
+cd django_airavata/apps/api/static/django_airavata_api
+yarn install && yarn dev
+```
-1. Build the Docker image.
+## Configuration
- ```
- docker build -t airavata-django-portal .
- ```
+The portal connects to the Airavata server via the Python SDK:
-2. Run the Docker container.
+```python
+# settings.py
+AIRAVATA_API_HOST = 'localhost'
+AIRAVATA_API_PORT = 9090
+GATEWAY_ID = 'default'
+```
- ```
- docker run -d \
- -v /path/to/my/settings_local.py:/code/django_airavata/settings_local.py \
- -p 8000:8000 airavata-django-portal
- ```
+## Docker
-3. Load an initial set of Wagtail pages (theme). You only need to do this when
- starting the container for the first time.
+```bash
+# Build
+docker build -t airavata-django-portal .
- ```
- docker exec CONTAINER_ID python manage.py load_cms_data new_default_theme
- ```
+# Run
+docker run -d \
+ -v /path/to/my/settings_local.py:/code/django_airavata/settings_local.py \
+ -p 8000:8000 airavata-django-portal
-4. Point your browser to http://localhost:8000.
+# Load initial CMS pages (first run only)
+docker exec CONTAINER_ID python manage.py load_cms_data new_default_theme
+```
### Multi-architecture images
-To build and push
-[multi-architecture images](https://docs.docker.com/desktop/multi-arch/), first
-create a builder (one time)
-
-```
+```bash
docker buildx create --name mybuilder --use
-```
-
-then run
-
-```
docker buildx build --pull --platform linux/amd64,linux/arm64 -t apache/airavata-django-portal:latest --push .
```
## Documentation
-Documentation currently is available at
-https://apache-airavata-django-portal.readthedocs.io/en/latest/ (built from the
-'docs' directory).
+Documentation is available at https://apache-airavata-django-portal.readthedocs.io/en/latest/
-To build the documentation locally, first
-[set up a development environment](#setting-up-development-environment), then
-run the following in the root of the project:
+To build locally:
-```
+```bash
mkdocs serve
```
-## Feedback
-
-Please send feedback to the mailing list at <de...@airavata.apache.org>. If you
-encounter bugs or would like to request a new feature you can do so in the
-[Airavata Jira project](https://issues.apache.org/jira/projects/AIRAVATA) (just
-select the _Django Portal_ component when you make your issue).
-
-## Customization
-
-See the Customization Guide in the
-[documentation](https://apache-airavata-django-portal.readthedocs.io/en/latest/)
-for information on how to customize the Airavata Django Portal user interface.
-To get started we recommend going through the
-[Gateways Tutorial](https://apache-airavata-django-portal.readthedocs.io/en/latest/tutorial/gateways_tutorial/).
-This tutorial covers the different ways that the user interface can be
-customized.
-
## Contributing
-For general information on how to contribute, please see the
-[Get Involved](http://airavata.apache.org/get-involved.html) section of the
-Apache Airavata website.
-
-### Setting up development environment
+See the [Get Involved](http://airavata.apache.org/get-involved.html) section of the Apache Airavata website.
-Run `pip install -r requirements-dev.txt` to install development and testing
-libraries.
+### Development
-Use a code editor that integrates with editorconfig and flake8. I also recommend
-autopep8 for automatically formatting code to follow the PEP8 guidelines.
-Prettier is used for formatting JavaScript and Vue.js code.
+```bash
+pip install -e ".[dev]"
+```
-See the docs for more information on
-[developing the backend](./docs/dev/developing_backend.md) and
-[frontend code](./docs/dev/developing_frontend.md).
+Uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting. Run `ruff check` and `ruff format` before committing.
-### Running Django Tests
+### Running Tests
-Run `./runtests.py` to run the Django unit tests.
+```bash
+./runtests.py
+```
## License
-The Apache Airavata Django Portal is licensed under the Apache 2.0 license. For
-more information see the [LICENSE](LICENSE) file.
+Apache License 2.0