{"id":21070414,"url":"https://github.com/stencila/sparkla","last_synced_at":"2025-03-14T02:42:00.848Z","repository":{"id":35272867,"uuid":"209234519","full_name":"stencila/sparkla","owner":"stencila","description":"✨ Compute sessions for executable documents","archived":false,"fork":false,"pushed_at":"2024-04-11T01:29:49.000Z","size":5683,"stargazers_count":2,"open_issues_count":54,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-13T23:05:15.515Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stencila.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-18T06:28:51.000Z","updated_at":"2024-05-03T19:44:44.589Z","dependencies_parsed_at":"2023-01-15T17:30:19.005Z","dependency_job_id":"8de635e0-0b08-4592-9c62-3b469eb6e1ba","html_url":"https://github.com/stencila/sparkla","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fsparkla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fsparkla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fsparkla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fsparkla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stencila","download_url":"https://codeload.github.com/stencila/sparkla/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243513561,"owners_count":20302965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T18:46:54.503Z","updated_at":"2025-03-14T02:42:00.820Z","avatar_url":"https://github.com/stencila.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ✨ Sparkla\n\n\u003e Compute sessions for executable documents: fast-to-start, isolated, reproducible. Pick any three.\n\n\u003e :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).\n\n## Install\n\n```bash\nnpm install -g @stencila/sparkla\n```\n\nSparkla creates sessions in either Firecracker microVMs or Docker containers. So you'll need at least one of these installed.\n\n### Firecracker\n\nFirecracker is only available on Linux.\nDownload the latest Firecracker binary from https://github.com/firecracker-microvm/firecracker/releases:\n\n```bash\ncurl -L -o firecracker https://github.com/firecracker-microvm/firecracker/releases/download/v0.18.0/firecracker-v0.18.0\nchmod +x firecracker\n```\n\nFirecracker 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:\n\n```bash\nsudo setfacl -m u:${USER}:rw /dev/kvm\n```\n\n### Docker\n\nIf you want to use Docker-based sessions then you'll need to have `docker` installed.\n\n## Usage\n\nRun Sparkla using the command line interface e.g.\n\n```bash\nsparkla serve --port 9001 --cpuTotal 1\n```\n\n### Options\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- OPTIONS-BEGIN --\u003e\n\n| Name            | Description                                                                                                              | Type                           | Default              |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | -------------------- |\n| debug           | Output debug level log entries?                                                                                          | boolean                        | false                |\n| host            | The host address that the server should listen on.                                                                       | string                         | \"127.0.0.1\"          |\n| port            | The port that the server should listen on.                                                                               | number                         | 9000                 |\n| jwtSecret       | The JWT secret to use to sign and verify JWT tokens. If `null` then a random secret will be generated.                   | string, null                   |  null                |\n| sessionType     | The class of sessions created.                                                                                           | \"firecracker\", \"docker\"        | \"docker\"             |\n| cpuTotal        | The total number of CPUs that can be allocated to sessions. `null` = use the number of CPUs on the machine.              | number, null                   |  null                |\n| 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                |\n| expiryInterval  | Interval in seconds between checks for expired sessions.                                                                 | number                         | 15                   |\n| durationWarning | Number of seconds to provide clients with a warning prior to reaching maximum session duration.                          | number                         | 600                  |\n| timeoutWarning  | Number of seconds to provide clients with a warning prior to a reaching session timeout.                                 | number                         | 60                   |\n| staleInterval   | Interval in seconds between checks for stale sessions.                                                                   | number                         | 60                   |\n| stalePeriod     | Number of seconds that a stopped session is considered stale and will be removed from the list of sessions.              | number                         | 3600                 |\n| statsInterval   | Interval in seconds for collecting system statistics                                                                     | number                         | 60                   |\n| statsPrometheus | The port to serve Prometheus compatible metrics on. Set to `0` to turn off Prometheus exporting.                         | number                         | 9464                 |\n| 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\" |\n| peerSwarm       | The name of the peer swarm to join.                                                                                      | string, null                   | \"sparkla\"            |\n\n\u003c!-- OPTIONS-END --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\nAll options can be set, in decending order of priority, by:\n\n- a command line argument e.g. `--port 80`\n- an environment variable prefixed with `SPARKLA_` e.g. `SPARKLA_PORT=80`\n- a `.json` or `.ini` configuration file, set using the `--config` option, or `.sparklarc` by default\n\n## Development\n\n```bash\nnpm run serve:dev\n```\n\n### Firecracker\n\nTo check for running `FirecrackerSession`s:\n\n```bash\nps aux | firecracker\n```\n\nYou can also check the logs and metrics of a Firecracker VM while it is running:\n\n```bash\ncat /tmp/vm-0d0b4b2fa73c5d4c10ed72ccac97b798530ba1b7ab8461fd313d320fb5d3562e/log.fifo\ncat /tmp/vm-0d0b4b2fa73c5d4c10ed72ccac97b798530ba1b7ab8461fd313d320fb5d3562e/metrics.fifo\n```\n\n### Docker\n\nTo check for running `DockerSession`s:\n\n```bash\ndocker ps\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fsparkla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstencila%2Fsparkla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fsparkla/lists"}