diff --git a/Dockerfile b/Dockerfile index 7f43200..5e3a4d0 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,8 +11,8 @@ RUN \ WORKDIR / -ENV PORT 8733 -ENV DEBUG_PORT 8520 +ENV PORT=8733 +ENV DEBUG_PORT=8520 ENV SDK_PATH=/sdk ENV TOITDOCS_VIEWER_PATH=/web_toitdocs diff --git a/README-dev.md b/README-dev.md new file mode 100644 index 0000000..2845e66 --- /dev/null +++ b/README-dev.md @@ -0,0 +1,34 @@ +# Toit package manager - development + +## Testing the image + +* Create a fresh repository or fork the existing registry repository. +* Create a new ssh-key: + ``` shell + ssh-keygen -t ed25519 + ``` +* Copy the public key into the deploy keys on GitHub: https://github.com/XXX/YYY/settings/keys. + Don't forget to add write-access. +* Create a known_hosts file: + ``` shell + ssh-keyscan github.com > known_hosts + ``` +* Start docker if not already running `sudo systemctl start docker` +* Run `make image`. Make sure `$HOME/go/bin` is in your path. +* Start the image (see the main README): + ``` shell + docker run -p 8733:8733 -e"REGISTRY_URL=github.com/XXX/YYY" -e"..." toit_registry + ``` + + +## Tips and tricks + +### Auto-update submodules + +Run + +``` +$ git config core.hooksPath .githooks +``` + +in the repository to auto-update sub modules. diff --git a/README.md b/README.md index f8aefe4..2e08374 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,95 @@ -# Toit Package Manager +# Toit package management server -Package server -============== -Run the package server with +A docker container that exposes a package registry for the Toit package manager. + +Features: +- List packages. +- Search. +- Automatic Toitdoc generation. +- API to register new packages or new versions of existing packages. + +## Deployment + +Run the docker container with the following variables: +- `REGISTRY_BRANCH` specifies the branch of the registry (for example `main`). +- `REGISTRY_URL` specifies the url of the registry to serve packages from (for + example `github.com/toitware/test-registry`). +- `REGISTRY_SSH_KEY_FILE` specifies the SSH key file inside the docker container + that grants read/write access to the registry. For example `/secrets/ssh-key`. +- `REGISTRY_SSH_KEY` is an alternative way to provide the SSH key as a string. + The `REGISTRY_SSH_KEY_FILE` path must still be set, and will be populated with + the content of the `REGISTRY_SSH_KEY` variable if the `REGISTRY_SSH_KEY_FILE` + doesn't exist. + +Use `REGISTRY_SSH_KEY_FILE` if you want to provide the key through a mounted volume. +Use `REGISTRY_SSH_KEY` if you want to provide the key as an environment variable. + +The default port is `8733`. You can change it by setting the `PORT` environment variable. + +### SSH known hosts + +The docker container has keys for github.com, gitlab.com and shell.sf.net. If your +registry is hosted on a different domain, you need to provide the known hosts file. +You can either provide the file through a volume and point `SSH_KNOWN_HOSTS` to it, +or you can inherit the container and add an updated known hosts file. + +## Example + +Using a volume for the SSH key: + +```shell +docker run -p 8733:8733 \ + -e REGISTRY_BRANCH=main \ + -e REGISTRY_URL=github.com/toitware/test-registry \ + -e REGISTRY_SSH_KEY_FILE=/secrets/ssh-key \ + -v /path/to/ssh-key:/secrets/ssh-key \ + toit_registry ``` -REGISTRY_BRANCH= REGISTRY_URL= REGISTRY_SSH_KEY_FILE= make run/registry + +Using an environment variable for the SSH key: + +```shell +docker run -p 8733:8733 \ + -e REGISTRY_BRANCH=main \ + -e REGISTRY_URL=github.com/toitware/test-registry \ + -e REGISTRY_SSH_KEY="$(cat /path/to/ssh-key)" \ + toit_registry ``` -Environment variable explanation: - - `REGISTRY_BRANCH` specifies the branch of the registry (e.g. `master`). - - `REGISTRY_URL`specifies the url of the registry to serve packages from (e.g. `github.com/toitware/test-registry`). - - `REGISTRY_SSH_KEY_FILE` specifies the SSH key file that grants read/write access to the registry (e.g. `/home/lau/toitware/toit/tools/tpkg/test-registry_deploy_key`). - - `REGISTRY_SSH_KEY` is an alternative way to provide the SSH key as a string. The `REGISTRY_SSH_KEY_FILE` path - must still be set, and will be populated with the content of the `REGISTRY_SSH_KEY` variable if the - `REGISTRY_SSH_KEY_FILE` doesn't exist. - -By default the server runs on port `8733` (set environment variable `PORT` to change this). - -Example uses: -Packages + +## API + +### Packages + +List all packages: ``` $ curl 127.0.0.1:8733/api/v1/packages {"result":{"package":{"name":"location","description":"Support for locations in a geographical coordinate system.","license":"MIT","url":"github.com/toitware/toit-location","latestVersion":"1.0.0"}}} {"result":{"package":{"name":"morse","description":"Functions for International (ITU) Morse code.","license":"MIT","url":"github.com/toitware/toit-morse","latestVersion":"1.0.2"}}} {"result":{"package":{"name":"morse_tutorial","description":"A tutorial version of the Morse package.","license":"MIT","url":"github.com/toitware/toit-morse-tutorial","latestVersion":"1.0.0"}}} ``` -Versions of a package + +### Versions of a package + +List all versions of a package: ``` $ curl 127.0.0.1:8733/api/v1/packages/github.com/toitware/toit-morse/versions {"result":{"version":{"name":"morse","description":"Functions for International (ITU) Morse code.","license":"MIT","url":"github.com/toitware/toit-morse","version":"1.0.0","dependencies":[]}}} {"result":{"version":{"name":"morse","description":"Functions for International (ITU) Morse code.","license":"MIT","url":"github.com/toitware/toit-morse","version":"1.0.1","dependencies":[]}}} {"result":{"version":{"name":"morse","description":"Functions for International (ITU) Morse code.","license":"MIT","url":"github.com/toitware/toit-morse","version":"1.0.2","dependencies":[]}}} ``` -Sync registry + +### Sync the registry + +Sync the registry: ``` $ curl -X POST 127.0.0.1:8733/api/v1/sync {} ``` -Register package -``` -$ curl -X POST 127.0.0.1:8733/api/v1/register/github.com/toitware/ubx-message/version/2.1.1 -{} -``` -For testing the image -===================== -* Create a fresh repository or fork the existing registry repository. -* Create a new ssh-key: - ``` shell - ssh-keygen -t ed25519 - ``` -* Copy the public key into the deploy keys on Github: https://github.com/XXX/YYY/settings/keys. - Don't forget to add write-acces. -* Create a known_hosts file: - ``` shell - ssh-keyscan github.com > known_hosts - ``` -* Start docker if not already running `sudo systemctl start docker` -* Run `make image` -* Start the image: - ``` shell - docker run -p 8733:8733 -e"REGISTRY_URL=github.com/XXX/YYY" toit-registry - ``` - - -Tips and Tricks -=============== - -## Auto-update submodules - -Run +### Register a package +Register a package: ``` -$ git config core.hooksPath .githooks +$ curl -X POST 127.0.0.1:8733/api/v1/register/github.com/toitware/ubx-message/version/2.1.1 +{} ``` - -in the repository to auto-update sub modules.