Development.md

Development

1. Clone the repository:

   git clone https://github.com/mgax/minivirt
   cd minivirt

2. Create a virtualenv so you don't interfere with gobally-installed packages:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install the repo in edit mode and development dependencies:

   pip install -e '.[devel]'

4. Run the test suite:

   pytest
   pytest --runslow  # if you're not in a hurry

Python API

Minivirt is written in Python and offers a straightforward API:

from minivirt.cli import db

alpine = db.get_image('alpine')
myvm = VM.create(db, 'myvm', image=alpine, memory=512)
with myvm.run(wait_for_ssh=30):
    print(myvm.ssh('uname -a', capture=True))

GitHub Actions self-hosted runners

Minivirt comes with a server that launches GitHub Actions runners when a workflow job is queued. Each runner is ephemeral and runs in its own VM.

1. Install extra dependencies:

   pip install -e minivirt[githubactions]

2. Build an actions runner image:

   miv build recipes/alpine-3.15.yaml --tag alpine-3.15 -v
   miv build recipes/ci-alpine.yaml --tag ci-alpine -v
   miv build recipes/githubactions-alpine.yaml --tag githubactions-alpine -v

3. Run the server. To interact with the GitHub API, it needs a GitHub PAT, and runs git credentials fill to retrieve it. It uses ngrok to listen for webhook events; to avoid the ngrok session timing out, set a token in the NGROK_AUTH_TOKEN environment variable.

   miv -v githubactions serve githubactions-alpine {repo}