docs: update readme (#60)

EXAMPLE.md

@@ -0,0 +1,168 @@
+## Getting Started
+
+To get familiarized, we will show how you can use these tools to answer two questions:
+
+- How do I sync secrets from one store to another?
+- How do I consume secrets to bootstrap my configs?
+
+To answer the first question, we shall create some database secrets and synchronize them into Vault.<br>
+For the second question, we will use some secrets from Vault to create an access file for an application.
+
+### 1. Prepare environment
+
+You will need the following tools to continue:
+- Docker
+- Git
+- Makefile
+- Golang `>= 1.21`
+
+To set up the environment, you can build from source:
+```bash
+git clone https://github.com/bank-vaults/secret-sync.git /tmp/secret-sync
+cd /tmp/secret-sync
+make build
+alias secret-sync="/tmp/secret-sync/build/secret-sync"
+```
+
+Alternatively, you can also use only Docker:
+```bash
+alias secret-sync="docker run --rm -v /tmp:/tmp ghcr.io/bank-vaults/secret-sync:latest secret-sync"
+```
+
+### 2. Define secret stores
+
+Documentation and examples on how to use different secret stores can be found in chapter [Secret Store](#secret-store).
+
+#### 2.1. Local store
+Create a directory and a config file to use as the _local secret store_.
+```bash
+# Create local store directory
+mkdir -p /tmp/example/local-store
+
+# Create local store config file
+cat <<EOF > /tmp/example/local-store.yml
+secretsStore:
+ local:
+ storePath: "/tmp/example/local-store"
+EOF
+```
+
+#### 2.2. Vault store
+Deploy Vault and create config file to use as the _Vault secret store_.
+```bash
+# Deploy a Vault instance
+docker compose -f dev/vault/docker-compose.yml up -d
+
+# Create Vault store config file
+cat <<EOF > /tmp/example/vault-store.yml
+secretsStore:
+ vault:
+ address: "http://0.0.0.0:8200"
+ storePath: "secret/"
+ authPath: "userpass"
+ token: "root"
+EOF
+```
+
+### 3. Define sync plans
+Documentation and examples on how to create a more extensive sync plan can be found in chapter [Sync Plan](#sync-plan).
+
+#### 3.1. Database secrets
+Define a sync plan for `db-host`, `db-user`, `db-pass` secrets.
+These secrets will be synced from our local to Vault secret store.
+
+```bash
+cat <<EOF > /tmp/example/db-secrets-sync.yml
+sync:
+ - secretQuery:
+ path: /
+ key:
+ regexp: db-(host|user|pass)
+EOF
+```
+
+#### 3.1. Application access secret
+Define a sync plan for app-specific secret `app-access-config` created from various other secrets (e.g. database).
+This secret will be synced from Vault to our local secret store (as a file).
+It can also be synced against the same store to refresh the secret.
+
+```bash
+cat <<EOF > /tmp/example/app-access-config-sync.yml
+sync:
+ - secretSources:
+ - name: selector
+ secretQuery:
+ path: /
+ key:
+ regexp: db-(host|user|pass)
+ target:
+ key: app-access-config
+ template:
+ data:
+ appID: "12345"
+ # ...some additional secrets for the given app...
+
+ # Secrets fetched from Vault will be encoded, we need to decode
+ hostname: "{{ .Data.selector.dbHost | base64dec }}"
+ username: "{{ .Data.selector.dbUser | base64dec }}"
+ password: "{{ .Data.selector.dbPass | base64dec }}"
+EOF
+```
+
+### 4. Create database secrets
+
+Create database access secrets in our local secret store.
+```bash
+echo -n "very-secret-hostname" > /tmp/example/local-store/db-host
+echo -n "very-secret-username" > /tmp/example/local-store/db-user
+echo -n "very-secret-password" > /tmp/example/local-store/db-pass
+```
+
+### 5. Perform sync
+
+Secret synchronization is performed using the [CLI](#syncing-with-cli) by executing the sync plan between source and target secret stores.
+
+#### 5.1. Database secrets
+
+To synchronize database secrets from our local to Vault secret store, run:
+
+```bash
+secret-sync --source "/tmp/example/local-store.yml" --target "/tmp/example/vault-store.yml" --sync "/tmp/example/db-secrets-sync.yml"
+```
+
+If successful, your output should contain something like:
+
+```json
+{"level":"info","msg":"Successfully synced action = 0 for key /db-user"}
+{"level":"info","msg":"Successfully synced action = 0 for key /db-pass"}
+{"level":"info","msg":"Successfully synced action = 0 for key /db-host"}
+{"level":"info","msg":"Synced 3 out of total 3 keys"}
+```
+
+You can also navigate to the local Vault instance and verify these secrets.
+
+#### 5.2. Application access secret
+
+To synchronize application access secret from Vault to our local secret store, run:
+
+```bash
+secret-sync --target "/tmp/example/local-store.yml" --source "/tmp/example/vault-store.yml" --sync "/tmp/example/app-access-config-sync.yml"
+```
+
+If successful, beside logs, you should also be able to find the app access secret via:
+
+```bash
+cat /tmp/example/local-store/app-access-config
+{"appID":"12345","hostname":"very-secret-hostname","password":"very-secret-password","username":"very-secret-username"}
+```
+
+
+### 6. Cleanup
+
+```bash
+# Destroy Vault instance
+docker compose -f dev/vault/docker-compose.yml down
+
+# Remove example files
+rm -rf /tmp/example
+```