Add readme and some docs

README.md

@@ -1,46 +1,29 @@
-# SMTP Relay Charm
+[![CharmHub Badge](https://charmhub.io/smtp-relay/badge.svg)](https://charmhub.io/smtp-relay)
+[![Publish to edge](https://github.com/canonical/smtp-relay-operator/actions/workflows/publish_charm.yaml/badge.svg)](https://github.com/canonical/smtp-relay-operator/actions/workflows/publish_charm.yaml)
+[![Promote charm](https://github.com/canonical/smtp-relay-operator/actions/workflows/promote_charm.yaml/badge.svg)](https://github.com/canonical/smtp-relay-operator/actions/workflows/promote_charm.yaml)
+[![Discourse Status](https://img.shields.io/discourse/status?server=https%3A%2F%2Fdiscourse.charmhub.io&style=flat&label=CharmHub%20Discourse)](https://discourse.charmhub.io)
 
-## Description
+# SMTP Relay Operator
 
-The SMTP Relay Charm installs a versatile postfix SMTP relay server.
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators)
+deploying and managing a postfix SMTP relay server on bare metal. SMTP
+is an Internet standard communication protocol for email transmission.
 
-It's intended to be highly configurable, setting up Postfix as requested.
+For information about how to deploy, integrate, and manage this charm, see the Official [smtp-relay Operator Documentation](https://charmhub.io/smtp-relay/docs).
 
-Features include (not limited to):
-- set up base Postfix system
-- relay through another MTA
-- set up virtual aliases and transport maps
-- restrict relaying per domain, sender, recipient, headers checks
-- enable SPF subsystem
-- set up authenticated submission service
-- restrict sender address per user
-- fine-tune TLS settings
-- set up limits (rate, size, connections, ...)
-- set up Nagios monitoring
-- set up rsyslog relaying and log retention
 
-## Usage
+## Get started
 
-Provision a Juju environment then deploy 2 units with:
+You can follow the tutorial [here](https://charmhub.io/smtp-relay/docs/getting-started).
 
-```
-juju deploy -n2 smtp-relay
-```
 
-### Scale Out Usage
+## Learn more
+* [Read more](https://charmhub.io/smtp-relay) <!--Link to the charm's official documentation-->
+* [Developer documentation](https://www.postfix.org/documentation.html) <!--Link to any developer documentation-->
+* [Official webpage](https://www.postfix.org/) <!--(Optional) Link to official webpage/blog/marketing content-->
+* [Troubleshooting](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) <!--(Optional) Link to a page or section about troubleshooting/FAQ-->
+## Project and community
+* [Issues](https://github.com/canonical/smtp-relay-operator/issues) <!--Link to GitHub issues (if applicable)-->
+* [Contributing](https://charmhub.io/smtp-relay/docs/how-to-contribute) <!--Link to any contribution guides-->
+* [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) <!--Link to contact info (if applicable), e.g. Matrix channel-->
 
-To horizontally scale, adding more read-only standbys:
-
-```
-juju add-unit smtp-relay
-```
-
----
-
-## Testing
-
-Just run `make unittest`.
-
----
-
-For more details, [see here](https://charmhub.io/smtp-relay/configure).

docs/how-to/contribute.md

@@ -0,0 +1,75 @@
+# How to contribute
+
+## Overview
+
+This document explains the processes and practices recommended for contributing enhancements to the SMTP Relay operator.
+
+- Generally, before developing enhancements to this charm, you should consider [opening an issue
+  ](https://github.com/canonical/smtp-relay-operator/issues) explaining your use case.
+- If you would like to chat with us about your use-cases or proposed implementation, you can reach
+  us at [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+  or [Discourse](https://discourse.charmhub.io/).
+- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library
+  will help you a lot when working on new features or bug fixes.
+- All enhancements require review before being merged. Code review typically examines
+  - code quality
+  - test coverage
+  - user experience for Juju operators of this charm.
+- Please help us out in ensuring easy to review branches by rebasing your pull request branch onto the `main` branch. This also avoids merge commits and creates a linear Git commit history.
+- Please generate src documentation for every commit. See the section below for more details.
+
+## Developing
+
+The code for this charm can be downloaded as follows:
+
+```
+git clone https://github.com/canonical/smtp-relay-operator
+```
+
+You can use the environments created by `tox` for development:
+
+```shell
+tox --notest -e unit
+source .tox/unit/bin/activate
+```
+
+### Testing
+
+* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`).
+* `tox -e fmt`: Runs formatting using `black` and `isort`.
+* `tox -e lint`: Runs a range of static code analysis to check the code.
+* `tox -e static`: Runs other checks such as `bandit` for security issues.
+* `tox -e unit`: Runs the unit tests.
+* `tox -e integration`: Runs the integration tests.
+
+### Generating src docs for every commit
+
+Run the following command:
+
+```bash
+echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+## Build charm
+
+Build the charm in this git repository using:
+
+```shell
+charmcraft pack
+```
+
+### Deploy
+
+```bash
+# Create a model
+juju add-model smtp-relay-dev
+# Enable DEBUG logging
+juju model-config logging-config="<root>=INFO;unit=DEBUG"
+# Deploy the charm (assuming you're on amd64)
+juju deploy ./smtp_relay_ubuntu-24.04-amd64.charm
+```
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the SMTP Relay Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.

docs/reference/actions.md

@@ -0,0 +1,5 @@
+# Actions
+
+See [Actions](https://charmhub.io/smtp-relay/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)

docs/reference/external_access.md

@@ -0,0 +1,3 @@
+# External access
+
+This charm does not require any external access.