Local Deployment · Quick Start

Running AV Studio Locally

How to start the AV Studio Python server on your machine and reach every page in the app. There is no build step and no front-end framework — just Python.

Runs at http://127.0.0.1:8000/ · Project folder: AV-Studio

Prerequisites

You only need Python. The app is served by a small Python HTTP server; the front end is vanilla JavaScript with no bundler.

What	Details
Python	Python 3.x (3.12+ recommended)
Internet	Required for the proxied API routes (`/profiles`, `/design`, `/schemas…`) that call Oracle ORDS.
Flask optional	Only needed for the Map Factory page. The server boots fine without it — see Map Factory setup below.

1Start the server

Open a terminal and run these two lines from the project root:

# go to the project folder
cd AV-Studio

# start the server
python3 server.py

This single command starts both servers — AV Workbench and, if Flask is installed, the Map Factory subprocess. A healthy startup prints two lines:

Startup line	Meaning
`Serving on http://127.0.0.1:8000` open this	AV Workbench — the URL you actually open in your browser.
`Map-Factory UI ready at http://127.0.0.1:5500` internal	Factory subprocess. Do not open port 5500 directly — reach it through the `/factory/*` proxy on port 8000.

Then open the app: http://127.0.0.1:8000/ — the links below only work once the server is running.

2Main pages

Click to open (the server must be running on port 8000). The top nav on every internal page is: Designer · Query · Maps · Data · Developer · Help.

Designer home

http://127.0.0.1:8000/

Main app — view/edit AV profile JSON, generate DDL.

Query

http://127.0.0.1:8000/query.html

Build and run queries against the AV.

Maps

http://127.0.0.1:8000/maps.html

Browse & curate the unified map collection catalog.

Map Factory needs Flask

http://127.0.0.1:8000/factory/

Produce new map assets (proxied to subprocess).

Calculation Builder

http://127.0.0.1:8000/calc-builder.html

Template-driven Oracle AV expression designer.

Data

http://127.0.0.1:8000/data.html

Data page.

Developer

http://127.0.0.1:8000/developer.html

Developer / debug page (former Settings tab).

Help

http://127.0.0.1:8000/help.html

Help page.

Validate

http://127.0.0.1:8000/validate.html

Validation runs & friendly error messages.

Bugs

http://127.0.0.1:8000/bugs.html

Bug report & resolution queue.

Dependencies

http://127.0.0.1:8000/dependencies.html

Dependencies & attributions inventory.

3Stop the server

In the terminal running the server, press:

Ctrl + C

AV Workbench's shutdown handler cleanly terminates the Map Factory subprocess too, so you don't need to stop port 5500 separately.

4Configuration

Host & port

Edit these constants near the top of server.py:

HOST = '127.0.0.1'
PORT = 8000

ORDS base URL

The Oracle ORDS base resolves from av_config.py (AV_BASE), and can be overridden per deployment with an environment variable before you start the server:

export AV_STUDIO_AV_BASE='https://<host>/ords/<schema>/avw'
python3 server.py

Map Factory settings

Factory subprocess & metadata DB settings live in factory_proxy.py: MAP_FACTORY_HOST, MAP_FACTORY_PORT, MAP_FACTORY_METADATA_DB.

Note: don't modify server.py's proxy config or API endpoints without explicit instruction.

5Map Factory setup first time only

The Map Factory page needs Flask and companions. If they aren't installed, the app still boots normally — the Maps tab's "Open Map Factory →" link just returns a 502 with install hints until you run:

pip install -r factory/requirements.txt

Then restart the server. From the user's point of view there is still one URL (port 8000) and one process to start.

6Run the tests

A small Python unittest suite lives in tests/:

python3 -m unittest discover -s tests

Typical startup

Open a terminal and cd into the AV-Studio project folder.
Run python3 server.py and wait for the two "Serving on…" lines.
Open http://127.0.0.1:8000/ — or any page above — in your browser.
When finished, return to the terminal and press Ctrl + C.

Troubleshooting

Symptom	Fix
Blank data or errors in the UI	Check the server console (the terminal running `python3 server.py`); verify internet / API access to ORDS.
Port 8000 already in use	Change `PORT` in `server.py`, restart, and browse to the new port.
Map Factory link returns 502	Run `pip install -r factory/requirements.txt`, then restart the server.
Factory subprocess port conflict (5500)	Change `MAP_FACTORY_PORT` in `factory_proxy.py`.
Where are the logs?	There is no log file — logs are written to stdout/stderr of the terminal running `server.py`.