Metadata-Version: 2.4
Name: cloudsim
Version: 1.0.2
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 with a CLI and backend server.

It is built to help you learn cloud concepts by creating VMs, load balancers, traffic simulations, and per-VM databases on your own machine.

## Cloud Architect Academy

Want a guided course version? Visit the academy:

[![Launch Academy](https://img.shields.io/badge/Academy_Site-Visit_Now-8A2BE2?style=for-the-badge&logo=googlescholar)](https://cloudsim-academy-v1.netlify.app/)

## Quickstart

Install:

```bash
pip install cloudsim
```

Create a workspace:

```bash
cloudsim config init --workspace ./cloudsim-workspace
```

Set the workspace for your current terminal if needed:

Windows PowerShell:

```powershell
$env:CLOUDSIM_WORKSPACE = (Resolve-Path .\cloudsim-workspace).Path
```

macOS/Linux:

```bash
export CLOUDSIM_WORKSPACE="$(pwd)/cloudsim-workspace"
```

On Windows, you can also set `CLOUDSIM_WORKSPACE` from the Environment Variables screen in the Start menu search.

If you save `CLOUDSIM_WORKSPACE` as a user environment variable, you only need to set it once.

Start the backend server:

```bash
cloudsim-server
```

If `cloudsim-server` is not available in your shell, use:

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

Leave that terminal open.

In a second terminal, check health:

```bash
cloudsim health
```

Create your first VM:

```bash
cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi
```

## What `cloudsim-server` Does

`cloudsim-server` starts the CloudSim backend API.

- Default URL: `http://127.0.0.1:5000`
- Keep it running while you use `cloudsim` commands in another terminal
- Commands like `vm create`, `state`, `lb create`, `simulate`, `expose`, and `call` talk to this backend
- If the launcher is not available in your shell, use `python -m cloudsim.app`

Quick check:

```bash
cloudsim health
```

## Your First End-to-End Flow

Start the backend:

```bash
cloudsim-server
```

Then in another terminal:

```bash
cloudsim health
cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi
```

Use the VM id returned by the create command:

```bash
cloudsim expose <vmId>
cloudsim call <vmId> /health
```

SSH into the VM workspace:

```bash
cloudsim ssh <vmId>
```

Use the VM id, not the VM name.

Create a script-based demo VM:

```bash
cloudsim vm create --name demo-vm --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi --runtime-mode python_script --script-path scripts/sample_app.py
```

## Workspace

CloudSim stores its runtime state in a workspace directory, not inside the installed package.

`cloudsim config init --workspace ./cloudsim-workspace` creates:

- `<workspace>/.env`
- `~/.cloudsim/config.json`

If you do not want a global default workspace file:

```bash
cloudsim config init --workspace ./cloudsim-workspace --no-default
```

Workspace resolution order:

1. `CLOUDSIM_WORKSPACE`
2. `~/.cloudsim/config.json`
3. current working directory

Files created in the workspace:

- `<workspace>/.cloudsim/simulation.db`
- `<workspace>/.cloudsim/sql_service.db`
- `<workspace>/vms/<vmId>/vm_state.db`
- `<workspace>/vms/<vmId>/vm_sqlite.db`
- `<workspace>/autoscale-vms/<vmId>/...`

## Common Commands

Check health:

```bash
cloudsim health
```

Show current state:

```bash
cloudsim state
```

Create a VM:

```bash
cloudsim vm create --name vm1 --region us-central1 --machine-type e2-micro --image ubuntu --backend-profile-id python-fastapi
```

List VMs:

```bash
cloudsim vm list
```

Open a VM shell:

```bash
cloudsim ssh <vmId>
```

Use the VM id returned by `cloudsim vm create`.

Create a load balancer:

```bash
cloudsim lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>
```

Run a traffic simulation:

```bash
cloudsim simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500
```

Provision per-VM SQLite:

```bash
cloudsim sql provision --vm-id <vmId>
cloudsim sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
cloudsim sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"
```

## Optional Real PostgreSQL Setup

If real PostgreSQL is configured and reachable, CloudSim can provision real database spaces. Otherwise it falls back to per-VM SQLite.

Set these in `<workspace>/.env`:

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

Then use:

```bash
cloudsim sql real-status
cloudsim sql real-provision --vm-id <vmId>
cloudsim sql real-connect --vm-id <vmId>
```

## Troubleshooting

If you see:

```text
Unable to reach backend at http://127.0.0.1:5000
```

then the backend is not running yet. Start it with:

```bash
cloudsim-server
```

If the workspace is not being picked up, set `CLOUDSIM_WORKSPACE` in your terminal or add it from the Windows Environment Variables search screen.

If port `5000` is busy, run the backend manually on another port:

```bash
python -c "from cloudsim.app import app; app.run(host='127.0.0.1', port=5052, debug=False)"
```

Then point the CLI to that port:

```bash
cloudsim --base-url http://127.0.0.1:5052 health
```

## Advanced

Most users do not need these, but they are available:

- Start backend via Python module: `python -m cloudsim.app`
- Run CLI via Python module: `python -m cloudsim.cli_services.runtime --help`
- Open a VM shell: `cloudsim ssh <vmId>`

If you installed with `pip` and `cloudsim` is not found, use a virtualenv or add your Python scripts directory to `PATH`.

## License

MIT (see `LICENSE`).
