diff --git a/README.md b/README.md
index ca13970..5eda5c2 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,22 @@
 # @lfk/selfservice
 
-runner selfservice portal
\ No newline at end of file
+runner selfservice portal
+
+## ⚡ Development
+### Requirements
+- Node.js v14.15.0 or newer
+- yarn package manager >= v1.22.10 < 2
+
+### Recommended Extensions
+- will be automatically recommended via `./vscode/extensions.json`
+- we also provide a config for i18n-ally in the `./vscode/` folder
+
+### Fastest Dev Environment
+- You can install the [Remote - Containers](https://github.com/Microsoft/vscode-remote-release) extension and use all recommended extensions and editor settings via the provided `./devcontainer/` config
+
+## 🔨 environment config
+- copy the `/public/env.sample.js` file to `/public/env.js`
+- set the required environment variables
+  - `documentserver_key`: url to the [document server](https://git.odit.services/lfk/document-server) instance
+  - `baseurl`: url to the main instance
+  - see [@lfk/deployment](https://git.odit.services/lfk/deployment) for a complete deployment guide
\ No newline at end of file
diff --git a/public/env.sample.js b/public/env.sample.js
index fc95691..1852851 100644
--- a/public/env.sample.js
+++ b/public/env.sample.js
@@ -1,6 +1,10 @@
 const config = {
+	// required
 	documentserver_key: '',
+	// required
 	baseurl: '',
+	// optional, will fallback to /imprint
 	url_imprint: '',
+	// optional, will fallback to /privacy
 	url_privacy: ''
 };