diff --git a/README.md b/README.md
index 75d5edcf3..73c586678 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,8 @@ You can either build preconfigured docker containers (database, backend and fron
 
 ### With Docker
 
+This is the recommended and only supported method of developing Thunderbird Appointment.
+
 ```bash
 git clone https://github.com/thunderbird/appointment
 cp appointment/backend/.env.example appointment/backend/.env
@@ -28,76 +30,10 @@ docker-compose up -d --build
 
 A MySQL database will be accessible via `localhost:3306` with username and password set to: `tba`
 
-To init database or run migrations, the backend offers a simple CLI interface:
-
-```bash
-run-command main update-db
-```
-
-### Manual Setup
-
-Make sure to have the following prerequisites available:
-
-```plain
-Python >= 3.11
-Node.js >= 16.0
-```
-
-Run application for development with hot reloading backend and frontend:
-
-1. Get the application data
-
-    ```bash
-    git clone https://github.com/thunderbird/appointment
-    ```
-
-2. Install, configure and run python backend (it's recommended to do this in a virtual environment)
-
-    ```bash
-    cd appointment
-    pip install .
-    touch backend/src/appointment.db # when using sqlite
-    cp backend/.env.example backend/.env # add your own configuration here
-    uvicorn --factory appointment.main:server --host 0.0.0.0 --port 5000
-    ```
-
-    You can now access the backend at [localhost:5000](http://localhost:5000).
-
-3. Install and run vue frontend in a second bash
-
-    ```bash
-    cd frontend
-    npm install
-    npm run dev
-    ```
-
-    You can now access the frontend at [localhost:8080](http://localhost:8080).
-
-4. (optional) Run database migrations
-
-    ```bash
-    cd backend
-    cp alembic.ini.example alembic.ini # add your own configuration here
-    alembic init migrations # init migrations once
-    alembic current # check database state
-    alembic upgrade head # migrate to latest state
-    alembic revision -m "create ... table" # create a new migration
-    ```
+On first-run the database will initialize, and a first time setup command will be triggered. Going forward database migrations will automatically run on `docker-compose up`.
 
 ## Testing
 
-To run tests in the backend, simply install the package in editing mode:
-
-```bash
-cd backend && pip install -e .
-```
-
-After this you can run tests with:
-
-```bash
-cd backend && python -m pytest
-```
-
 To run tests in the frontend, do:
 
 ```bash
@@ -108,31 +44,9 @@ cd frontend && npm test
 
 Contributions are very welcome. Please lint/format code before creating PRs.
 
-### Backend
-
-Backend is formatted using Ruff.
-
-```bash
-pip install ruff
-```
-
-Commands (from git root)
-
-```bash
-ruff check backend
-ruff check backend --fix
-```
-
-### Frontend
-
-Frontend is formatted using ESlint with airbnb rules.
-
-Commands (from /frontend)
-
-```bash
-npm run lint
-npm run lint --fix
-```
+Check out the project's respective readmes:
+* [Backend Readme](backend/README.md)
+* [Frontend Readme](frontend/README.md)
 
 ### Localization
 
diff --git a/backend/README.md b/backend/README.md
index bfb291f4e..4003a9541 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -4,24 +4,50 @@ This is the backend component of Thunderbird Appointment written in Python using
 
 ## Installation / Running
 
-### Development
-
-A docker file with instructions is provided for development use, please check [appointment/readme.md](../README.md) for more information.
-
 ### Self-hosting
 
 More information will be provided in the future. There is currently a docker file provided which we use to deploy to AWS' ECS which should help you get started.
 
-## Configuration
+### Configuration
+
+The backend project uses dotenv files to inject environment variables into the application. A starting template can be found as [.env.example](.env.example). Copy that as your `.env` to get started.
 
-The backend project uses dotenv files to inject environment variables into the application. A starting template can be found as [.env.example](.env.example). Copy that as your .env to get started.
+On first run (via [dev-entry.sh](scripts/dev-entry.sh)) a setup command will run filling in some secret environment variables, and the database will initialize.
 
-You will want to ensure any variable ending with `_SECRET` has a secret value assigned. Additionally there are values such as SMTP settings for mail, google authentication credentials for google oauth flow with the google calendar api, and zoom api credentials available.
+After that Appointment should be fully usable, however you may want to setup some third-party integrations like Google Calendar connections, or the creation of Zoom meetings. These are clearly labelled in the `.env` file, simply setup accounts for them with the vendor, and enter your values in the `.env` file.
+
+### Linting
+
+Backend is formatted using Ruff.
+
+```bash
+pip install ruff
+```
+
+Commands
+
+```bash
+ruff check 
+```
 
 ### Authentication
 
 This project is deployed with Mozilla Accounts (known as fxa in the code.) Since Mozilla Accounts is for internal use you will need to use password authentication. Note: password authentication does not currently have a registration flow.
 
+### Testing
+
+To run tests in the backend, simply install the package in editing mode:
+
+```bash
+cd backend && pip install -e .
+```
+
+After this you can run tests with:
+
+```bash
+cd backend && python -m pytest
+```
+
 ## Commands
 
 Backend has a light selection of cli commands available to be run inside a container.
@@ -40,9 +66,11 @@ run-command main --help
 │ download-legal                                                 │
 │ update-db                                                      │
 │ create-invite-codes                                            │
+│ setup                                                          │
 ╰────────────────────────────────────────────────────────────────╯
 ```
 
 * `download-legal` is an internal command to process privacy policy and terms of service files that will be served by the frontend.
 * `update-db` runs on docker container entry, and ensures the latest db migration has run, or if it's a new db then to kickstart that.
 * `create-invite-codes n` is an internal command to create invite codes which can be used for user registrations. The `n` argument is an integer that specifies the amount of codes to be generated.
+* `setup` a first run setup that fills in some missing environment variables.
diff --git a/frontend/README.md b/frontend/README.md
index 7523e7788..3ef652d7b 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,33 +1,41 @@
-# frontend
+# Thunderbird Appointment Frontend
+
+This is the frontend component of Thunderbird Appointment. It's written in VueJS with Vite.
 
 ## Project setup
 
+Copy the [.env.example](.env.example) as `.env`. 
+
+Then simply run:
 ```bash
-npm install
+yarn install
 ```
 
 ### Compiles and hot-reloads for development
 
 ```bash
-npm run serve
+yarn run serve
 ```
 
 ### Compiles and minifies for production
 
 ```bash
-npm run build
+yarn run build
 ```
 
 ### Lints and fixes files
 
+Frontend is formatted using ESlint with airbnb rules.
+
 ```bash
-npm run lint
+yarn run lint
+yarn run lint --fix
 ```
 
 ### Run tests
 
 ```bash
-npm test
+yarn run test
 ```
 
 ### Customize configuration