diff --git a/.env.sample b/.env.sample
new file mode 100644
index 0000000..ca40eec
--- /dev/null
+++ b/.env.sample
@@ -0,0 +1,12 @@
+RPC_URL=<!-- your EVM RPC websockets url -->
+ALCHEMY_API_KEY=<!-- your Alchemy API KEY -->
+
+ALERT_BOT_DISCORD_TOKEN=<!-- a discord bot access token -->
+ALERT_BOT_DISCORD_CLIENT=<!-- a discord bot application ID -->
+
+GOOEYLYTICS_DISCORD_TOKEN=<!-- a discord bot access token -->
+GOOEYLYTICS_DISCORD_CLIENT=<!-- a discord bot application ID -->
+
+GOOEY_BOT_DISCORD_TOKEN=<!-- a discord bot access token -->
+GOOEY_BOT_DISCORD_APP_ID=<!-- a discord bot application ID -->
+GOOEY_BOT_GUILD_ID=<!-- a discord channel ID -->
\ No newline at end of file
diff --git a/README.md b/README.md
index ca7d48b..41984ce 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,31 @@
-# Stateful Discord Bot Stack
\ No newline at end of file
+# Stateful Discord Bot Stack
+
+note, some of the bots used here are in a private git repository.
+make sure you are using authenticated credentials to pull them into this repo
+
+### Set up
+
+Clone each bot into this project directory, for example:
+
+```sh
+git clone https://git.ssh.surf/MrTuxedo/gwei-alert-bot/
+```
+
+Populate env vars for each bot in `.env`: see [.env.sample](./.env.sample) for expected values.
+
+### Spin up bot stack
+
+```sh
+docker compose up -d
+```
+
+### Updates
+
+Sometimes you may want to rebuild a bot to incorporate upstream changes without interupting the other services in the stack.  To do this:
+
+```sh
+cd gwei-alert-bot
+git pull
+cd ..
+docker compose up gwei-alert-bot --build --force-recreate -d
+```
\ No newline at end of file