# iVistaar Installation Guide

**Version:** 0.6.12 (always check `VERSION` in this package)  
**Platform:** Windows Server with IIS  
**Git:** not required on the target server  
**Package:** obfuscated customer build (not a full source tree)

iVistaar turns a Windows Server into an internal deployment control plane. Connect a project folder on the server, deploy, and get an organization-reachable URL in minutes.

See **CHANGELOG.md** for what changed between releases.

---

## 1. Prerequisites

Complete these once on the Windows Server before installing iVistaar.

| Requirement | Notes |
|---|---|
| Windows Server | With IIS enabled |
| IIS Management Scripts and Tools | Required for the install script |
| HttpPlatformHandler | [Download from Microsoft / IIS.net](https://www.iis.net/downloads/microsoft/httpplatformhandler) |
| **Python 3.10 or newer** | Python **2.7 is not supported**. Prefer a current install under `%LOCALAPPDATA%\Programs\Python\` |
| Administrator access | Install script must run elevated |

Git is **not** required.

### Enable IIS features (if needed)

In an elevated PowerShell session:

```powershell
Install-WindowsFeature Web-Server, Web-Mgmt-Tools, Web-Scripting-Tools
```

Then install **HttpPlatformHandler** from the link above and reboot if prompted.

---

## 2. Download and extract

1. Download the latest release zip from the product site  
   (`https://vistaar-c5o.pages.dev/downloads/iVistaar-latest.zip`).
2. Extract to a permanent location, for example:

```text
C:\iVistaar
```

After extraction you should see:

```text
C:\iVistaar\
  INSTALL.md
  INSTALL.txt
  README.md
  CHANGELOG.md
  RELEASE.txt
  VERSION
  wsgi.py
  requirements.txt
  admin\
  scripts\
  sample-apps\
  templates\
```

---

## 3. Install the iVistaar admin site

Open **Command Prompt or PowerShell as Administrator**, then run from the extracted folder:

```powershell
cd C:\iVistaar
.\scripts\install-admin.cmd -Port 8080
```

Use `install-admin.cmd` (not the `.ps1` alone). The `.cmd` wrapper unblocks extracted scripts and runs the installer in-memory so Restricted / “not digitally signed” policies are less likely to block it.

The installer auto-discovers **Python 3.10+** (`py -3`, common install folders, then PATH). It **rejects Python 2.7**. If discovery fails, pass the full path:

```powershell
.\scripts\install-admin.cmd -Port 8080 -PythonPath "C:\Users\<you>\AppData\Local\Programs\Python\Python314\python.exe"
```

### Optional parameters

| Parameter | Example | Purpose |
|---|---|---|
| `-Port` | `8080` | HTTP port for the admin site |
| `-HostHeader` | `ivistaar.company.com` | Bind a hostname |
| `-PythonPath` | `C:\...\Python314\python.exe` | Explicit Python 3.10+ interpreter |
| `-AppsRoot` | `C:\iVistaar\apps` | Deploy build root (default: `D:\iVistaar\apps` if D: exists, else `<install>\apps`) |
| `-SiteName` | `iVistaar` | IIS site name |
| `-AppPoolName` | `IVistaar_Admin` | IIS app pool name |
| `-PhysicalPath` | `C:\software\ivistaar` | Install root if not next to `scripts\` |

Hostname example:

```powershell
.\scripts\install-admin.cmd -Port 80 -HostHeader "ivistaar.company.com"
```

### What the installer does

- Locates a usable Python 3.10+ (never Python 2.7)
- Creates a Python virtual environment under the install folder `venv\`
- Installs Flask and Waitress
- Creates IIS app pool `IVistaar_Admin` (No Managed Code)
- Creates/updates IIS site `iVistaar` with your port/host binding
- Writes `web.config` with **absolute** `processPath`, `PYTHONPATH`, and stdout log path
- Sets `IVISTAAR_PYTHON` so auto-deploy uses the same Python 3 for app venvs
- Grants `IIS_IUSRS` modify rights on the install tree and apps root
- Prepares the apps root for application builds

---

## 4. Sign in

Open the admin URL, for example:

```text
http://localhost:8080/
```

| Field | Value |
|---|---|
| Username | `admin` |
| Password | `iV!5taar#Ctrl2026` |

Change the password before exposing the site beyond a trusted network:

1. Sign in → open **Account** in the top nav (or follow the dashboard banner).
2. Enter the current password, then a new password (10+ characters) and confirm.
3. Click **Update password**. The new password is stored hashed in `data\ivistaar.db`.

You can still set `IVISTAAR_ADMIN_USER` / `IVISTAAR_ADMIN_PASSWORD` in the install environment for the initial password. After you change it in **Account**, the UI password wins until you clear `admin_settings.password_hash` in the database (recovery).

### Licensing (freemium)

| Tier | Projects |
|---|---|
| **Free demo** | Up to **3** sites |
| **Pro** | Unlimited — yearly **SPC** from the iVistaar team |

- The dashboard shows your current license status.
- At the free limit, **Connect** shows a contact screen instead of a new deploy form.
- Open **License** in the nav, paste your SPC, and activate.
- When a Pro SPC expires, the install falls back to Free until you enter a new yearly code.

Contact: **hello@ivistaar.com**

---

## 5. Deploy your first application

iVistaar uses a Render-style flow: **connect a project folder**, then deploy.

1. Place your Python project on the server (or a reachable UNC path), for example:

```text
C:\Projects\my-dashboard
```

The folder should contain your entrypoint (typically `app.py`) and `requirements.txt`.

Supported sample stacks: **Flask**, **FastAPI**, **Streamlit**, and **Gradio**.  
Streamlit/Gradio need service mode (`install-admin-service.cmd`).

2. In iVistaar, open **Connect**.
3. Enter the project folder path, a service name, and optional slug.
4. Click **Deploy**.

iVistaar will:

- Sync the folder into its build directory
- Create a per-app virtual environment with **Python 3.10+**
- Install dependencies and Waitress
- Provision an IIS application under `/apps/<slug>/`
- Record a deployment **event** and archive a **release** for rollback

Your app URL will look like:

```text
http://localhost:8080/apps/my-dashboard/
```

### Auto-deploy

With auto-deploy enabled (default), iVistaar watches the connected folder. When Python sources or `requirements.txt` change (including size increases), it records a detection event and redeploys automatically. You can toggle auto-deploy per project on the project page.

### Events and rollback

- Open **Events** in the nav for a global deployment history, or filter by project.
- Events include **actor**, **source mtime**, and optional **source owner**.
- On the project page, use **Releases** → **Rollback** to restore a prior successful build.

### Start, stop, and remove

On the project page you can **Start**, **Stop**, **Redeploy**, or **Delete** a deployment. Deleting removes the iVistaar build copy and IIS application — your original project folder is not deleted.

### Sample applications

| Folder | Entrypoint | Framework |
|---|---|---|
| Path (after unzip) | Entrypoint | Stack |
|---|---|---|
| `C:\iVistaar\sample-apps\hello-flask` | `app:app` | Flask |
| `C:\iVistaar\sample-apps\hello-dash` | `app:server` | Dash |
| `C:\iVistaar\sample-apps\hello-fastapi` | `app:app` | FastAPI |
| `C:\iVistaar\sample-apps\hello-streamlit` | `streamlit:app.py` | Streamlit |
| `C:\iVistaar\sample-apps\hello-gradio` | `app:demo` | Gradio |

Customer downloads ship samples as **`.zip` files only**. Unzip first, e.g.:

```powershell
cd C:\iVistaar\sample-apps
Expand-Archive .\hello-flask.zip -DestinationPath .\hello-flask
```

**Dash tip:** Expose `server = app.server` and set the Connect entrypoint to `app:server` or `run:server` (match the filename).  
From **v0.6.12**, iVistaar injects `/apps/<slug>/` for Dash automatically — you normally do **not** need `requests_pathname_prefix` in `run.py`. If you use `from dash import Dash`, call `Dash(...)` (not `dash.Dash(...)` unless you also `import dash`).

### FAQ — common deploy errors

| Symptom | Fix |
|---|---|
| IIS HTTP 500, empty logs | `install-admin-service.cmd -Port 8080` |
| pandas build / vswhere error | Use Python 3.11–3.12 or newer pandas wheels (e.g. ≥2.3.3 on 3.14) |
| Dash Loading… / DashRenderer undefined | Entrypoint `*:server`, redeploy on 0.6.12+, hard-refresh |
| `NameError: dash is not defined` | Use `Dash(...)` after `from dash import Dash` |
| WinError 32 on `runtime.log` | Upgrade to 0.6.9+ or stop the app task, then redeploy |
| Python 2.7 selected | Install Python 3.10+ / pass `-PythonPath` |
| Cannot add 4th project | Activate SPC on License page |

More detail: admin UI **Help**, or the FAQ on the product site.

Connect any of those paths for a first successful deploy. See `sample-apps\README.md`.

### UNC paths

Paths like `\\laptop\share\project` work when the IIS app pool identity can read the share and the share is online at deploy time.

---

## 6. Upgrade iVistaar

1. Download the newer `iVistaar-x.y.z.zip` (or `iVistaar-latest.zip`).
2. In IIS Manager, stop the `IVistaar_Admin` app pool.
3. Extract the new zip over `C:\iVistaar` (**keep** the existing `data\` folder — it holds deployment history and license state).
4. Re-run:

```powershell
cd C:\iVistaar
.\scripts\install-admin.cmd -Port 8080
```

5. Start the `IVistaar_Admin` app pool.
6. Confirm **License** still shows your expected tier (Pro SPC is stored under `data\`).

---

## 7. Troubleshooting

| Symptom | What to check |
|---|---|
| `install-admin.ps1` cannot be loaded / not digitally signed | Use `.\scripts\install-admin.cmd` (unblocks scripts + in-memory run). If a domain policy still blocks it, run the elevated one-liner in the tip below, or `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |
| `C:\Python27\python.exe: No module named venv` | Python 2.7 was selected. Install Python 3.10+ and pass `-PythonPath`, or re-run so auto-discovery finds Python 3 |
| Wrong `python.exe` (user-local vs machine) | Pass the full path, e.g. `%LOCALAPPDATA%\Programs\Python\Python314\python.exe` |
| `ModuleNotFoundError: No module named 'wsgi'` | Always run Waitress / tools from the **install root** (folder that contains `wsgi.py`), not from `scripts\` |
| `PermissionError: [WinError 10013]` on the port | Another IIS site (or process) already bound that port — stop it or choose another `-Port` |
| Blank page / HTTP 500 / 502, **no logs at all** | HttpPlatformHandler is not starting Python. Run `.\scripts\install-admin-service.cmd -Port 8080` (Waitress scheduled task; bypasses IIS process hosting). Or `.\scripts\repair-admin.cmd` / `.\scripts\diagnose-admin.cmd` |
| `/apps/<slug>/` returns **404** while admin works | Re-run `.\scripts\install-admin-service.cmd -Port 8080` (v0.6+), then **Redeploy** the app. |
| `/apps/<slug>/` returns **500/502** while admin works | IIS HttpPlatformHandler cannot run the app Python. Use **v0.6.1+** service mode (`IVISTAAR_APP_HOSTING=waitress`): re-run `install-admin-service.cmd`, then Redeploy so the app runs as its own Waitress task. |
| Auto-deploy / app venv fails with Python 2.7 | Re-run the installer so `web.config` sets `IVISTAAR_PYTHON` to Python 3; delete the broken app `venv\` folder and Redeploy |
| Install script fails on IIS commands | Confirm Management Scripts/Tools and elevated shell |
| Deploy cannot see project folder | Path must exist for the app pool identity; for UNC shares, grant read access to that account |
| Cannot add a 4th project | Free demo limit — open **License** or email hello@ivistaar.com for an SPC |
| SPC activation fails | Confirm the code is typed exactly; check expiry date embedded in the code |

### Manual Waitress smoke test (optional)

If IIS is misbehaving, verify the admin app outside IIS from the **install root**:

```powershell
cd C:\iVistaar
.\venv\Scripts\python.exe -m waitress --listen=127.0.0.1:8080 wsgi:app
```

Stop any IIS site already using that port first. Do not paste control characters into the command line.

### Execution policy still blocks the installer

If `install-admin.cmd` reports the script is not digitally signed, run this from an **elevated** Command Prompt in the install folder:

```powershell
Unblock-File .\scripts\*.ps1
& ([scriptblock]::Create((Get-Content -Raw .\scripts\install-admin.ps1))) -Port 8080 -PhysicalPath (Get-Location).Path
```

Or once per user:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Then re-run `.\scripts\install-admin.cmd -Port 8080`.

Deployment logs for each app are shown on the deployment detail page in the admin UI and under the iVistaar data logs directory.

---

## Support notes

- Current package is **v0.6.12**: Dash auto URL prefix, in-product Help FAQ, Waitress hosting, multi-framework samples. See **PROJECT_STATE.md** / **CHANGELOG.md**.
- Default authentication is for first setup only — change it before wider exposure.
- Linux targets and Git-based connect on the server are out of scope for this package.
- Product site: https://vistaar-c5o.pages.dev · Support: hello@ivistaar.com