From 96b762405599a04625e52f2081650d3ee8010311 Mon Sep 17 00:00:00 2001 From: Jordan Doyle Date: Tue, 28 Sep 2021 23:20:14 +0100 Subject: [PATCH] Make on start on the Book, installation instructions --- book/.gitignore | 1 + book/book.toml | 6 ++++++ book/src/SUMMARY.md | 8 ++++++++ book/src/introduction.md | 25 +++++++++++++++++++++++++ book/src/getting-started/index.md | 6 ++++++ book/src/getting-started/installation.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ book/src/getting-started/user-guide.md | 1 + book/src/guide/index.md | 1 + 8 files changed, 108 insertions(+) diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..7585238 100644 --- /dev/null +++ a/book/.gitignore @@ -1,0 +1,1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..329850a 100644 --- /dev/null +++ a/book/book.toml @@ -1,0 +1,6 @@ +[book] +authors = ["Jordan Doyle"] +language = "en" +multilingual = false +src = "src" +title = "Chartered" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..0f7ae72 100644 --- /dev/null +++ a/book/src/SUMMARY.md @@ -1,0 +1,8 @@ +# Summary + +[Introduction](./introduction.md) + +- [Getting Started](./getting-started/index.md) + - [Server Installation](./getting-started/installation.md) + - [User Guide](./getting-started/user-guide.md) +- [Chartered Guide](guide/index.md)diff --git a/book/src/introduction.md b/book/src/introduction.md new file mode 100644 index 0000000..2a940b5 100644 --- /dev/null +++ a/book/src/introduction.md @@ -1,0 +1,25 @@ +# chartered ✈️ + +Chartered is an [alternative registry][arp] implementation that goes a little +bit futher than your bog-standard registry, providing AAA (authentication, +authorisation & accounting) guarentees for each of your crates. + +[arp]: https://doc.rust-lang.org/cargo/reference/registries.html + +### Sections + +**[Getting Started](getting-started/index.md)** + +To get started with Chartered, running the servers & uploading your first +crate. + +**[Chartered Guide](guide/index.md)** + +The guide will give you the run down on all things chartered. + +**Appendices:** +* [Glossary](appendix/glossary.md) + +**Other documentation:** +* [Changelog](https://github.com/w4/chartered/releases) +* [Cargo book](https://doc.rust-lang.org/cargo/index.html) diff --git a/book/src/getting-started/index.md b/book/src/getting-started/index.md new file mode 100644 index 0000000..d6b806c 100644 --- /dev/null +++ a/book/src/getting-started/index.md @@ -1,0 +1,6 @@ +# Getting Started + +To get started with Chartered, run the server and upload your first crate. + +- [Server installation](./installation.md) +- [User guide](./user-guide.md) diff --git a/book/src/getting-started/installation.md b/book/src/getting-started/installation.md new file mode 100644 index 0000000..fe66040 100644 --- /dev/null +++ a/book/src/getting-started/installation.md @@ -1,0 +1,60 @@ +# Server Installation + +Chartered's server comes in 3 parts: + +- **chartered-git**: hosts the git server which clients grab the crate index from, along with + their credentials to grab the crates from the next service, +- **chartered-web**: hosts the API portion of chartered, which serves the crates themselves + (or a redirect to them, depending on which storage backend you're using) and hosts the "web + API" which is consumed by our final service, +- **chartered-frontend**: a React-based [crates.io](https://crates.io/)-like web UI for viewing + crates, managing organisations and viewing AAA data. + +Each of these services are hosted separately from one another, and could technically be swapped +out for other implementations - the only shared layer between the three of them is database +storage for crate lookups and authentication credential vending. + +### Backend Services + +`chartered-git` and `chartered-web`'s setups are similar, first they need a database set up - +either SQLite or PostgreSQL, PostgreSQL is recommended anywhere outside of development/local +use for obvious reasons. + +Both the aformentioned services have sane defaults for development and can be ran simply by +running the binary, the services will bind to `127.0.0.1:8899` and `127.0.0.1:8080` respectively +and store crate files in `/tmp/chartered`, configuration away from these defaults is simple. + +Using the recommended setup, S3 & PostgreSQL: + +```toml +bind-address = "127.0.0.1:8080" +database-uri = "postgres://user:password@localhost/chartered" + +# unlike the above two options, this configuration value should only be supplied +# for chartered-web +crate-store = "s3://s3-eu-west-1.amazonaws.com/my-cool-crate-store/" +``` + +Or, using the defaults as an example: + +```toml +bind-address = "127.0.0.1:8899" +database-uri = "sqlite://chartered.db" +crate-store = "file:///tmp/chartered" +``` + +These configuration files can be passed into each binary using the `-c` CLI argument. + +Alternative crate stores will be considered, please consider contributing or +[create an issue on GitHub][gh-issue]. MySQL support, however, is a no-go. + +[gh-issue]: https://github.com/w4/chartered/issues + +### Frontend + +The frontend only needs to be configured to point to the `chartered-web` service. This can be +done by changing the bundled `config.json`. This can then be hosted in S3/minio/your preferred +static hosting platform, a Dockerfile is also built which uses [`sfz`][sfz] to run on your own +server without another way of hosting static content. + +[sfz]: https://github.com/weihanglo/sfzdiff --git a/book/src/getting-started/user-guide.md b/book/src/getting-started/user-guide.md new file mode 100644 index 0000000..cd3d452 100644 --- /dev/null +++ a/book/src/getting-started/user-guide.md @@ -1,0 +1,1 @@ +# User Guide diff --git a/book/src/guide/index.md b/book/src/guide/index.md new file mode 100644 index 0000000..dd448db 100644 --- /dev/null +++ a/book/src/guide/index.md @@ -1,0 +1,1 @@ +# Chartered Guide -- rgit 0.1.3