diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..9a47c2de
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,21 @@
+# Example environment variables for CHAI project
+# Copy this file to .env and adjust values as needed
+
+# Database connection
+CHAI_DATABASE_URL=postgresql://postgres:s3cr3t@localhost:5435/chai
+PGPASSWORD=s3cr3t
+
+# Scheduler
+ENABLE_SCHEDULER=true
+FREQUENCY=24
+
+# Pipeline behavior
+TEST=false
+FETCH=true
+NO_CACHE=false
+
+# Docker service variables
+# (uncomment and set as needed)
+# SERVICE=package_managers
+
+# Other environment variables can be added below as needed
diff --git a/README.md b/README.md
index e36ce318..6d361554 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
 # CHAI
+[![CI](https://github.com/teaxyz/chai/actions/workflows/ci.yml/badge.svg)](https://github.com/teaxyz/chai/actions/workflows/ci.yml)
 
 CHAI is an attempt at an open-source data pipeline for package managers. The
 goal is to have a pipeline that can use the data from any package manager and
@@ -102,6 +103,30 @@ There are many other potential use cases for this data:
    will connect you to the database.
 2. If you're orchestrating via docker, swap `localhost` for `host.docker.internal`
 
+## Troubleshooting / Common Errors
+
+### Docker Compose fails to start db
+- Make sure port 5435 is not already used by another service.
+- If you get a permission error on the data folder, run your terminal as administrator or fix the permissions for the `./data` folder.
+
+### Migration error (alembic)
+- Ensure you have run `docker compose build --no-cache db alembic` before `docker compose up alembic`.
+- Check that the `CHAI_DATABASE_URL` environment variable is set correctly.
+
+### Database connection refused
+- Make sure the `db` service is healthy before starting other services.
+- If you are using Docker Desktop on Windows/Mac, use `host.docker.internal` as the database host.
+
+### Out of disk space
+- Fetching package manager data can consume more than 5GB. Ensure you have enough storage before running the pipeline.
+
+### Permission denied when deleting ./data
+- Run `rm -rf ./data` with administrator/root privileges.
+
+### Service stuck or not responding
+- Check logs with `docker compose logs <service>` to see detailed errors.
+- Restart the service with `docker compose restart <service>`.
+
 ## Managing Dependencies
 
 We use [`uv`](https://astral.sh/uv) to manage dependencies (and sometimes execution).
diff --git a/api/.env.example b/api/.env.example
new file mode 100644
index 00000000..ca8bfd2c
--- /dev/null
+++ b/api/.env.example
@@ -0,0 +1,6 @@
+# Example environment variables for CHAI API service
+# Copy this file to .env and adjust values as needed
+
+DATABASE_URL=postgresql://postgres:s3cr3t@localhost:5435/chai
+HOST=0.0.0.0
+PORT=8080