diff --git a/README.md b/README.md
index 763fedf..225b78c 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@ System for managing species lists in the ALA.
 
 This consists of two components:
 
-* lists-ui - Web application for managing species lists
-* lists-service - Spring boot REST and GraphQL web services for accessing, modifying species lists
+* [lists-ui](lists-ui) - Web application for browsing and managing species lists
+* [lists-service](lists-service) - Spring boot REST and GraphQL web services for accessing, modifying species lists
 
 
 ## Architecture
diff --git a/lists-service/README.md b/lists-service/README.md
index 64c6801..d6db8d4 100644
--- a/lists-service/README.md
+++ b/lists-service/README.md
@@ -1,3 +1,33 @@
-# Docker builds
+# List service - GraphQL and REST services for species lists
+
+This is the back end for the species-lists project.
+It is a Spring Boot application that provides REST and GraphQL web services for accessing, modifying species lists.
+
+## Getting started
+
+```bash
+./gradlew bootRun
+```
+
+## Elasticsearch and MongoDB
+
+To run the elasticsearch and mongodb containers, use the following command:
+
+```bash
+docker-compose -f src/main/docker/docker-compose.yml up
+```
+
+## GraphQL
+
+The GraphQL test interface is available at `http://localhost:8080/graphiql`.
+
+## REST
+
+The Swagger UI for REST services are available at `http://localhost:8080`.
+
+
+# Docker hub
+
+The docker images for list-service are available on [docker hub](https://hub.docker.com/r/atlasoflivingaustralia/lists-service). 
+Commits to this `develop` branch will result in a new image being built and pushed to the `latest` tag on docker hub.
 
-docker buildx build --push -t "atlasoflivingaustralia/lists-service:$(git rev-parse --short HEAD)" -f src/main/docker/Dockerfile .
\ No newline at end of file
diff --git a/lists-ui/README.md b/lists-ui/README.md
index 197005e..6344f69 100644
--- a/lists-ui/README.md
+++ b/lists-ui/README.md
@@ -13,4 +13,31 @@ yarn run dev
 
 ```bash
 yarn run build
+```
+
+## Environment variables
+
+The following environment variables are used:
+
+```properties
+VITE_DOWNLOAD_URL=http://localhost:8080/download
+VITE_UPLOAD_URL=http://localhost:8080/upload
+VITE_INGEST_URL=http://localhost:8080/ingest
+VITE_DELETE_URL=http://localhost:8080/delete
+VITE_GRAPHQL_URL=http://localhost:8080/graphql
+VITE_METADATA_URL=http://localhost:8080/metadata
+VITE_REINDEX_URL=http://localhost:8080/reindex
+VITE_REMATCH_URL=http://localhost:8080/rematch
+VITE_MIGRATE_URL=http://localhost:8080/migrate
+VITE_HOME_URL=https://www.ala.org.au
+VITE_LOGO_URL=https://www.ala.org.au/app/uploads/2019/01/logo.png
+VITE_OIDC_AUTH_SERVER=https://auth-test.ala.org.au/cas/oidc
+VITE_OIDC_AUTH_PROFILE=https://auth-test.ala.org.au/userdetails/myprofile
+VITE_SIGNUP_URL=https://auth-test.ala.org.au/userdetails/registration/createAccount
+VITE_OIDC_CLIENT_ID=TO_BE_ADDED
+VITE_OIDC_REDIRECT_URL=http://localhost:5173
+VITE_OIDC_SCOPE=TO_BE_ADDED
+VITE_ROLE_ADMIN=ROLE_ADMIN
+VITE_APP_MAPBOX_TOKEN=TO_BE_ADDED
+VITE_APP_BIE_URL=https://bie.ala.org.au
 ```
\ No newline at end of file