diff --git a/README.md b/README.md
index a98ed8b..de482b9 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,28 @@
 
 [![Build Status](https://drone.autonomic.zone/api/badges/coop-cloud/keycloak/status.svg)](https://drone.autonomic.zone/coop-cloud/keycloak)
 
-> https://www.keycloak.org
\ No newline at end of file
+[Keycloak](https://www.keycloak.org) + Coöp Cloud.
+
+<!-- metadata -->
+* **Category**: Apps
+* **Status**: ❷💛
+* **Image**: [`jboss/keycloak`](https://hub.docker.com/r/jboss/keycloak), ❶💚, upstream
+* **Healthcheck**: Yes
+* **Backups**: ?
+* **Email**: ❸🍎
+* **Tests**: ❷💛
+* **SSO**: N/A
+<!-- endmetadata -->
+
+## Basic usage
+
+1. Set up Docker Swarm and [`abra`][abra]
+2. Deploy [`coop-cloud/traefik`][cc-traefik]
+3. `abra app new keycloak --secrets` (optionally with `--pass` if you'd like
+   to save secrets in `pass`)
+4. `abra app YOURAPPDOMAIN config` - be sure to change `$DOMAIN` to something that resolves to
+   your Docker swarm box
+5. `abra app YOURAPPDOMAIN deploy`
+
+[abra]: https://git.autonomic.zone/autonomic-cooperative/abra
+[compose-traefik]: https://git.autonomic.zone/compose-stacks/traefik