Metadata-Version: 2.4
Name: cloudsim
Version: 1.0.0
Summary: Local-first cloud infrastructure simulator (Flask API + CLI).
Author: CloudSim
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask==3.1.0
Requires-Dist: psycopg[binary]==3.2.3
Requires-Dist: pymongo==4.10.1
Dynamic: license-file

# CloudSim

CloudSim is a local-first cloud infrastructure simulator (Flask API + CLI) designed to teach you how the cloud works.

---

## Cloud Architect Academy
Want to learn the cloud step-by-step? We've built a premium interactive course website just for you.

[![Launch Academy](https://img.shields.io/badge/Academy_Site-Visit_Now-8A2BE2?style=for-the-badge&logo=googlescholar)](http://localhost:5173)

---

## Install

### PyPI (normal)
```bash
pip install cloudsim
```

### TestPyPI (testing)
TestPyPI does not mirror all dependencies, so include the real PyPI index for dependencies:
```bash
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cloudsim==1.0.2
```

## Configuration (.env)

Fastest setup:
```bash
cloudsim config init --workspace ./cloudsim-workspace
cloudsim config show

# Start API
cloudsim-server
```

`cloudsim config init` writes:
- `<workspace>/.env` (your environment config)
- `~/.cloudsim/config.json` (default workspace pointer, so you can run `cloudsim` from any folder)

If you do not want a global default workspace file, use:
```bash
cloudsim config init --workspace ./cloudsim-workspace --no-default
```

CloudSim reads environment variables from a workspace `.env` file:
- `<workspace>/.env`

If you installed via `pip`, an example file is also included inside the installed package at `cloudsim/.env.example`.
To print its path:
```bash
python -c "import cloudsim; from pathlib import Path; print(Path(cloudsim.__file__).resolve().parent / '.env.example')"
```

Quick start (PowerShell):
```powershell
$env:CLOUDSIM_WORKSPACE = "E:\\codex\\cloudsim-workspace"
New-Item -ItemType Directory -Force $env:CLOUDSIM_WORKSPACE | Out-Null
Copy-Item .\\.env.example "$env:CLOUDSIM_WORKSPACE\\.env"
```

Quick start (macOS/Linux):
```bash
export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
mkdir -p "$CLOUDSIM_WORKSPACE"
cp ./.env.example "$CLOUDSIM_WORKSPACE/.env"
```

PostgreSQL (optional, for "real" Cloud SQL):
- `CLOUDSIM_PG_HOST=127.0.0.1`
- `CLOUDSIM_PG_PORT=5432`
- `CLOUDSIM_PG_ADMIN_USER=postgres`
- `CLOUDSIM_PG_ADMIN_PASSWORD=pg123`
- `CLOUDSIM_PG_ADMIN_DB=postgres`

If these are not set (or Postgres is not reachable), CloudSim continues to work using per-VM SQLite by default.

## Workspace (Where VMs/DBs Are Created)

CloudSim writes runtime state into a *workspace* directory (not inside the installed package directory).

Workspace resolution order:
1. `CLOUDSIM_WORKSPACE`
2. `~/.cloudsim/config.json` (`workspace`) (created by `cloudsim config init`)
3. current working directory

Windows (PowerShell):
```powershell
$env:CLOUDSIM_WORKSPACE = "E:\codex\cloudsim-workspace"
```

macOS/Linux:
```bash
export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
```

Files created in the workspace:
- `<workspace>/.cloudsim/simulation.db` (global state)
- `<workspace>/.cloudsim/sql_service.db` (simulated Cloud SQL accounts/tenancy)
- `<workspace>/vms/<vmId>/vm_state.db` (per-VM state snapshot)
- `<workspace>/vms/<vmId>/vm_sqlite.db` (per-VM SQLite database)
- `<workspace>/autoscale-vms/<vmId>/...` (autoscaled VMs)

## Start Backend API

```bash
python -m cloudsim.app
```

Default API base URL: `http://127.0.0.1:5000`

## CLI: Run Globally Or Inside A VM Shell

There are two common ways to use CloudSim CLI:

### A) Global CLI (works immediately, no PATH changes)
```bash
python -m cloudsim.cli_services.runtime --help
python -m cloudsim.cli_services.runtime health
```

### B) Direct `cloudsim` command (global install)
`pip install cloudsim` installs a launcher (`cloudsim` / `cloudsim.exe`) into your Python scripts folder.
You can run `cloudsim` directly only if that scripts folder is on your `PATH`.

Windows: find user-base
```powershell
python -m site --user-base
```
Add `<user-base>\Scripts` to `PATH`, open a new terminal, then:
```powershell
cloudsim --help
```

macOS/Linux: find user-base
```bash
python -m site --user-base
```
Add `<user-base>/bin` to `PATH`, open a new terminal, then:
```bash
cloudsim --help
```

Example paths:
- Windows (Microsoft Store Python): `C:\Users\CHIRAG\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts`
- Windows (python.org installer, common): `C:\Users\CHIRAG\AppData\Roaming\Python\Python313\Scripts`
- macOS/Linux (common): `$HOME/.local/bin`

### C) Direct `cloudsim` command (virtualenv)
Activating a venv automatically adds its scripts folder to `PATH`, so `cloudsim` works inside that venv.

Windows (PowerShell):
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
cloudsim --help
```

Windows (cmd):
```bat
python -m venv .venv
.\.venv\Scripts\activate.bat
cloudsim --help
```

macOS/Linux:
```bash
python -m venv .venv
source .venv/bin/activate
cloudsim --help
```

## VM Shell (`cloudsim ssh`)

`cloudsim ssh <vmId>` opens a VM workspace shell and sets VM context variables:
- `CLOUDSIM_IN_VM_SHELL=1`
- `CLOUDSIM_VM_ID=<vmId>`
- `CLOUDSIM_VM_SPACE=vm_<vmId>`

From inside the VM shell, per-VM commands can auto-target that VM (example: per-VM SQLite).

## Create A VM

```bash
python -m cloudsim.cli_services.runtime vm create \
  --name vm1 \
  --region us-central1 \
  --machine-type e2-micro \
  --image "Ubuntu 22.04 LTS" \
  --backend-profile-id python-fastapi
```

## Per-VM SQLite (Default "Cloud SQL" Fallback)

```bash
python -m cloudsim.cli_services.runtime sql provision --vm-id <vmId>
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "INSERT INTO items(name) VALUES (?)" --params-json '["alpha"]'
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"
```

## Load Balancer + Traffic Simulation

```bash
python -m cloudsim.cli_services.runtime lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>
python -m cloudsim.cli_services.runtime simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500
```

## Autoscale Demo

```bash
python -m cloudsim.cli_services.runtime autoscale-test --requests 1000 --max-instances 5
```

## Real PostgreSQL (Optional)

Set these env vars (or use `<workspace>/.env`) before starting the backend:
- `CLOUDSIM_PG_HOST=...`
- `CLOUDSIM_PG_PORT=...`
- `CLOUDSIM_PG_ADMIN_USER=...`
- `CLOUDSIM_PG_ADMIN_PASSWORD=...`
- `CLOUDSIM_PG_ADMIN_DB=...`

Then:
```bash
python -m cloudsim.cli_services.runtime sql real-status
python -m cloudsim.cli_services.runtime sql real-provision --vm-id <vmId>
python -m cloudsim.cli_services.runtime sql real-connect --vm-id <vmId>
```

## License

MIT (see `LICENSE`).
