https://github.com/stencila/sparkla
✨ Compute sessions for executable documents
https://github.com/stencila/sparkla
Last synced: over 1 year ago
JSON representation
✨ Compute sessions for executable documents
- Host: GitHub
- URL: https://github.com/stencila/sparkla
- Owner: stencila
- License: apache-2.0
- Created: 2019-09-18T06:28:51.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-11T01:29:49.000Z (about 2 years ago)
- Last Synced: 2024-04-13T23:05:15.515Z (about 2 years ago)
- Language: TypeScript
- Homepage:
- Size: 5.42 MB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 54
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ✨ Sparkla
> Compute sessions for executable documents: fast-to-start, isolated, reproducible. Pick any three.
> :warning: Well, that's the aim ;) Sparkla is currently in early development. It started as an experiment in using Amazon's Firecracker as a more secure (but just as fast-to-start) alternative to Docker containers. It is intended to supersede [`stencila/cloud`](https://github.com/stencila/cloud).
## Install
```bash
npm install -g @stencila/sparkla
```
Sparkla creates sessions in either Firecracker microVMs or Docker containers. So you'll need at least one of these installed.
### Firecracker
Firecracker is only available on Linux.
Download the latest Firecracker binary from https://github.com/firecracker-microvm/firecracker/releases:
```bash
curl -L -o firecracker https://github.com/firecracker-microvm/firecracker/releases/download/v0.18.0/firecracker-v0.18.0
chmod +x firecracker
```
Firecracker is built on top of KVM and needs read/write access to `/dev/kvm`. Log in to the host in one terminal and set up that access:
```bash
sudo setfacl -m u:${USER}:rw /dev/kvm
```
### Docker
If you want to use Docker-based sessions then you'll need to have `docker` installed.
## Usage
Run Sparkla using the command line interface e.g.
```bash
sparkla serve --port 9001 --cpuTotal 1
```
### Options
| Name | Description | Type | Default |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------------------- |
| debug | Output debug level log entries? | boolean | false |
| host | The host address that the server should listen on. | string | "127.0.0.1" |
| port | The port that the server should listen on. | number | 9000 |
| jwtSecret | The JWT secret to use to sign and verify JWT tokens. If `null` then a random secret will be generated. | string, null | null |
| sessionType | The class of sessions created. | "firecracker", "docker" | "docker" |
| cpuTotal | The total number of CPUs that can be allocated to sessions. `null` = use the number of CPUs on the machine. | number, null | null |
| memoryTotal | The total number amount of memory (Gib) that can be allocated to sessions. `null` = use the total amount of memory on the machine. | number, null | null |
| expiryInterval | Interval in seconds between checks for expired sessions. | number | 15 |
| durationWarning | Number of seconds to provide clients with a warning prior to reaching maximum session duration. | number | 600 |
| timeoutWarning | Number of seconds to provide clients with a warning prior to a reaching session timeout. | number | 60 |
| staleInterval | Interval in seconds between checks for stale sessions. | number | 60 |
| stalePeriod | Number of seconds that a stopped session is considered stale and will be removed from the list of sessions. | number | 3600 |
| statsInterval | Interval in seconds for collecting system statistics | number | 60 |
| statsPrometheus | The port to serve Prometheus compatible metrics on. Set to `0` to turn off Prometheus exporting. | number | 9464 |
| logsSentry | The Sentry DSN (Data Source Name) to record warning and error log entries. Set to `null` to not send logs to Sentry. | string | "https://7a4f9c9b0ef5474596c0066bb364e615@sentry.io/1818023" |
| peerSwarm | The name of the peer swarm to join. | string, null | "sparkla" |
All options can be set, in decending order of priority, by:
- a command line argument e.g. `--port 80`
- an environment variable prefixed with `SPARKLA_` e.g. `SPARKLA_PORT=80`
- a `.json` or `.ini` configuration file, set using the `--config` option, or `.sparklarc` by default
## Development
```bash
npm run serve:dev
```
### Firecracker
To check for running `FirecrackerSession`s:
```bash
ps aux | firecracker
```
You can also check the logs and metrics of a Firecracker VM while it is running:
```bash
cat /tmp/vm-0d0b4b2fa73c5d4c10ed72ccac97b798530ba1b7ab8461fd313d320fb5d3562e/log.fifo
cat /tmp/vm-0d0b4b2fa73c5d4c10ed72ccac97b798530ba1b7ab8461fd313d320fb5d3562e/metrics.fifo
```
### Docker
To check for running `DockerSession`s:
```bash
docker ps
```