# ambient-run -- build safely and securely in a local virtual machyine

`ambient-run` builds a software project in a local virtual machine,
safely and securely


## Example

A software developer would use this program to build their project in
a tightly controlled environment like this:

```sh
$ ambient-run build myproject.yaml
```

## Discussion

`ambient-run` is the first component of Ambient CI, which will be a
continuous integration system. The build is run in a virtual machine
that does not have any networking, mainly for security. All source and
dependencies are provided to the build, when it start, as the lack of
networking means it can't, for example, download them at build time.
The lack of networking also means the build can't leak secrets or
attack other computers over the network.

## Stakeholders

* Lars Wirzenius is the instigator and primary developer.
* Daniel Silverstone is an advisor.

## Requirements

See [`ambient-run.md`] for detailed requirements and acceptance
criteria.

## Architecture

`ambient-run` runs a VM using QEMU. The VM is given the source code
and dependencies using read-only virtual drives. It will also be
provided read-write drives for caching and for output artifacts. All
drives contain tar archives, not file systems, to make them easier,
safer, and more secure to deal with.

## Building

To build the documentation, run:

~~~sh
$ make
~~~

To build the software, run the usual Rust command:

~~~sh
$ cargo build
~~~

## Testing


To run the automated test suite, you need to first have a virtual
machine image for Ambient. The base image for
[ambient-build-vm](https://codeberg.org/ambient/ambient-build-vm) will
do fine. Set the `IMAGE` environment variable to the path to that
image when running the test suite:

~~~sh
$ IMAGE=/path/to/base.qcow2 cargo test
~~~

The reason the image is needed is that the test suite runs tests using
the virtual machine, to make sure `ambient-run` works.

## Deployment

To create a binary to install, run:

~~~sh
$ cargo install --path=.
~~~

There is a `debian/` directory with rudimentary Debian packaging,
which can be build in the usual Debian way.

## Contributing

See <https://codeberg.org/ambient/ambient-run> for the public git
repository. Please open issues, or send patches, via that.

## Legalese

Copyright 2023 Lars Wirzenius.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
 .
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.
 .
You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.