Improve README.

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

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.

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=<branch> REGISTRY_URL=<registry-url> REGISTRY_SSH_KEY_FILE=<ssh-key-path> 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.