# iVistaar Installation Guide

**Version:** 0.5.0 (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.exe` on PATH, or note the full path for the installer |
| Administrator access | Install script must run in an elevated PowerShell session |

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 **PowerShell as Administrator**:

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

### Optional parameters

| Parameter | Example | Purpose |
|---|---|---|
| `-Port` | `8080` | HTTP port for the admin site |
| `-HostHeader` | `ivistaar.company.com` | Bind a hostname |
| `-PythonPath` | `C:\Python312\python.exe` | If `python` is not on PATH |
| `-SiteName` | `iVistaar` | IIS site name |
| `-AppPoolName` | `IVistaar_Admin` | IIS app pool name |

Hostname example:

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

### What the installer does

- Creates a Python virtual environment under `C:\iVistaar\venv`
- Installs Flask and Waitress
- Creates IIS app pool `IVistaar_Admin` (No Managed Code)
- Creates IIS site `iVistaar` with your port/host binding
- Writes `web.config` for HttpPlatformHandler
- Prepares `D:\iVistaar\apps` 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 these credentials before exposing the site beyond a trusted network. Set `IVISTAAR_ADMIN_USER` and `IVISTAAR_ADMIN_PASSWORD` in the site `web.config` environment variables (re-run or edit after install).

### 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 Flask 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`.

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
- 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 application

```text
C:\iVistaar\sample-apps\hello-flask
```

Connect that path for a first successful deploy.

### 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.ps1 -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 |
|---|---|
| Blank page or HTTP 502 | `C:\iVistaar\logs\stdout_admin.log` |
| Install script fails on IIS commands | Confirm Management Scripts/Tools and elevated PowerShell |
| `httpPlatformHandler` errors | Install HttpPlatformHandler, then recycle the app pool |
| Deploy cannot see project folder | Path must exist for the app pool identity; for UNC shares, grant read access to that account |
| `pip` / venv failures | Confirm Python works: `python --version` |
| 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 |

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.5.0**: freemium licensing, License UI, auto-deploy, Events, release rollback, obfuscated customer build.
- 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