docs: restructure following diataxis

CONTRIBUTING.md

@@ -1,21 +1,84 @@
 # Contributing
 
+Notary is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+
 ## Getting Started
-You can build and run the program by following these steps:
 
-1. Install Go and Nodejs
-2. Fork the repository on GitHub
-3. Clone the forked repository to your local machine
-4. Build the frontend: `npm i --prefix ui && npm run build --prefix ui`
-5. Install the project: `go install ./...`
-6. Create a `config.yaml` file as described in README.md
-7. Run the project: `notary -config config.yaml`
+This tutorial guides you through setting up a development environment for Notary.
+
+After going through these steps, you will have a general idea of how to build and run Notary.
+
+### Prerequisites
+
+Install Go:
+```bash
+sudo snap install go --classic
+```
+
+Install NodeJS:
+```bash
+curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
+NODE_MAJOR=20
+echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
+sudo apt update
+sudo apt install nodejs
+```
+
+Clone the repository:
+
+```bash
+[email protected]:canonical/notary.git
+```
+
+### Build Notary
+
+Install the npm dependencies:
+
+```bash
+npm install --prefix ui 
+```
+
+Build the frontend:
+
+```bash
+npm run build --prefix ui
+```
+
+Build the Go binary:
+
+```bash
+go build -o notary cmd/notary/main.go
+```
+
+### Run Notary
 
-Commands assume you're running them from the top level git repo directory
+Create a certificate and private key:
 
-## Testing
+```bash
+openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1 -out cert.pem -subj "/CN=example.com"
+```
 
-### Unit Tests
+Create a `notary.yaml` file with the following content:
+
+```yaml
+key_path:  "key.pem"
+cert_path: "cert.pem"
+db_path: "certs.db"
+port: 3000
+pebble_notifications: false
+```
+
+Run Notary:
+
+```bash
+./notary -config notary.yaml
+```
+
+Access the Notary UI at `https://localhost:3000`.
+
+## How-to Guides
+
+### Run Unit Tests
 
 Run go unit tests by running:
 ```bash
@@ -27,25 +90,43 @@ Run frontend vitest test suite by running:
 npm run test --prefix ui
 ```
 
-### Lint
+### Run Lint checks
 
 Run the linter for golang by running:
 ```bash
 golangci-lint run ./...
 ```
+
 Run the linter for typescript by running:
 ```bash
 npm run lint
 ```
 
-## Creating the Container Image
+### Create a container Image
 
-We use rockcraft to create OCI images for use in container technologies like docker. 
-You can create the container and import it into docker by running:
+Install rockcraft:
+```bash
+sudo snap install rockcraft --classic
+```
+
+Build the container image:
 
 ```bash
 rockcraft pack -v
+```
+
+Copy the container image to the docker daemon:
+```bash
 version=$(yq '.version' rockcraft.yaml)
 sudo rockcraft.skopeo --insecure-policy copy oci-archive:notary_${version}_amd64.rock docker-daemon:notary:${version}
+```
+
+Run the container image:
+
+```bash
 docker run notary:${version}
-```
+```
+
+## Reference
+
+- [Go Best Practices Guidelines](https://docs.google.com/document/d/1IbFXyeXYlfQ5GUEEScGS7pP335Cei-5cFBdAoR973pQ/edit?tab=t.0)

README.md

@@ -1,10 +1,16 @@
-# notary
+# Notary
 
 Notary is a simple, reliable, and secure certificate management tool. Use it to request, approve, and manage certificate requests for your services. 
 
-## Installation
+### Project & Community
 
-### From Snap
+Notary is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+
+- To contribute to the code Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for guidelines and best practices.
+- Raise software issues or feature requests in [GitHub](https://github.com/canonical/notary/issues)
+- Meet the community and chat with us on [Matrix](https://matrix.to/#/!yAkGlrYcBFYzYRvOlQ:ubuntu.com?via=ubuntu.com&via=matrix.org&via=mozilla.org)
+
+## Getting Started
 
 Install the snap:
 ```bash
@@ -23,32 +29,27 @@ sudo snap start notary.notaryd
 
 Navigate to `https://localhost:3000` to access the Notary UI.
 
-### From OCI Image
+## How-to Guides
+
+### Install
+
+#### Snap
 
 ```bash
-# Pull the OCI image from github and run it in docker
-docker pull ghcr.io/canonical/notary:latest
-docker run -d --name notary -p 3000:3000 ghcr.io/canonical/notary:latest
-# Push the 3 required files and restart the workload
-docker exec notary /usr/bin/pebble mkdir -p /etc/notary/config
-docker exec notary /usr/bin/pebble mkdir -p /var/lib/notary/database
-docker cp key.pem notary:/etc/notary/config/key.pem
-docker cp cert.pem notary:/etc/notary/config/cert.pem
-docker cp config.yaml notary:/etc/notary/config/config.yaml
-docker restart notary
+sudo snap install notary
 ```
 
-### From Source
-
-go and npm CLI tools need to be installed in order to build notary from source.
-You will need to build the frontend first, and then install notary with Go.
+#### Charmed Operator
 
 ```bash
-npm install --prefix ui && npm run build --prefix ui && go install ./...
-notary -config ./config.yaml
+juju deploy notary-k8s
 ```
 
-## Configuration
+For more information on using Notary in the Juju ecosystem, read the [charm documentation](https://charmhub.io/notary-k8s).
+
+## Reference
+
+### Configuration
 
 Notary takes a YAML config file as input. The config file can be passed to Notary using the `-config` flag.
 
@@ -79,7 +80,7 @@ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1 -out cert.pem
 
 Notary does not support insecure http connections.
 
-## API
+### API
 
 | Endpoint                                               | HTTP Method | Description                                    | Parameters         |
 | ------------------------------------------------------ | ----------- | ---------------------------------------------- | ------------------ |