Skip to content

Commit 5f16402

Browse files
mjaquierymjaquiery
committed
docs
1 parent cd3c5b5 commit 5f16402

File tree

4 files changed

+230
-14
lines changed

4 files changed

+230
-14
lines changed

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
# odk-central
1+
# IB ODK Central Wrapper
2+
3+
This repository has two components:
4+
- [CDK](cdk/README.md): An AWS CDK stack to deploy a minimal ODK Central instance on AWS.
5+
- [Wrapper API](odk-wrapper/README.md): A TypeScript REST API for securely extracting and modifying ODK Central submission data.
6+
7+
See the individual README files for each component for detailed instructions on setup and usage.

‎cdk/README.md‎

Lines changed: 107 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,111 @@
1-
# Welcome to your CDK TypeScript project
1+
# ODK Central CDK Deployment
22

3-
This is a blank project for CDK development with TypeScript.
3+
This repository contains an AWS CDK stack to deploy a **minimal instance of [ODK Central](https://docs.getodk.org/central-install/)** on a single EC2 instance.
44

5-
The `cdk.json` file tells the CDK Toolkit how to execute your app.
5+
The stack provisions:
66

7-
## Useful commands
7+
- A public EC2 instance running Ubuntu with Docker and Docker Compose
8+
- Automatic installation and launch of ODK Central
9+
- Route 53 DNS record pointing to the instance
10+
- ACM certificate for HTTPS
11+
- Optional environment variable injection from AWS Secrets Manager
12+
- Configurable disk size and AMI
813

9-
* `npm run build` compile typescript to js
10-
* `npm run watch` watch for changes and compile
11-
* `npm run test` perform the jest unit tests
12-
* `npx cdk deploy` deploy this stack to your default AWS account/region
13-
* `npx cdk diff` compare deployed stack with current state
14-
* `npx cdk synth` emits the synthesized CloudFormation template
14+
Once the stack is running, you can access ODK Central via the provided domain name.
15+
You'll also need to connect to the instance via one of the AWS connection methods (SSH, SSM, etc.) to complete the setup.
16+
Follow the ODK Central guide on [setting up users](https://docs.getodk.org/central-install-digital-ocean/#logging-into-central) to set up an admin user.
17+
18+
---
19+
20+
## 📦 Prerequisites
21+
22+
- Node.js (>= 16)
23+
- AWS CDK v2
24+
- AWS CLI with appropriate credentials (or use `--profile`)
25+
- A Route 53 public hosted zone
26+
- An EC2 key pair (to SSH in if needed)
27+
28+
---
29+
30+
## 🛠 Configuration
31+
32+
Edit your `cdk.json` file to set the deployment context:
33+
34+
```json
35+
{
36+
"context": {
37+
"domainName": "oxrse.uk",
38+
"fullDomainName": "odk-central-test.oxrse.uk",
39+
"secretName": "odk-central/env-vars",
40+
"keyName": "your-keypair-name",
41+
"instanceVolumeSize": 30,
42+
"ubuntuAmiId": "ami-079b5e5b29763ec7c"
43+
}
44+
}
45+
````
46+
47+
| Key | Description |
48+
| -------------------- | ----------------------------------------------------------------------------- |
49+
| `domainName` | Root domain (must exist in Route 53) |
50+
| `fullDomainName` | Fully-qualified domain name (used in DNS and SSL cert) |
51+
| `secretName` | (Optional) Name of an AWS Secrets Manager secret with env vars (JSON format) |
52+
| `keyName` | Name of your existing EC2 key pair |
53+
| `instanceVolumeSize` | Root volume size in GB |
54+
| `ubuntuAmiId` | AMI ID for a basic Ubuntu image (no LVM), recommended for clean disk resizing |
55+
56+
---
57+
58+
## 🚀 Deploy
59+
60+
```bash
61+
cdk deploy --profile your-aws-profile
62+
```
63+
64+
This will:
65+
66+
1. Lookup your Route 53 zone
67+
2. Launch a t3.micro EC2 instance
68+
3. Install Docker, Docker Compose, and ODK Central
69+
4. Configure HTTPS via ACM
70+
5. Inject environment variables from Secrets Manager (if configured)
71+
6. Set up a DNS A record pointing your FQDN to the instance
72+
73+
---
74+
75+
## 🔐 Secrets Format
76+
77+
If you use the `secretName` context key, the secret's value should be a **JSON object** of key-value pairs. For example:
78+
79+
```json
80+
{
81+
"DOMAIN": "odk-central-test.oxrse.uk",
82+
"EMAIL": "admin@example.com",
83+
"SSL_TYPE": "letsencrypt"
84+
}
85+
```
86+
87+
These will be made available to the instance as shell environment variables and appended to ODK Central’s `.env`.
88+
89+
---
90+
91+
## 🧼 Cleanup
92+
93+
To destroy all provisioned resources:
94+
95+
```bash
96+
cdk destroy --profile your-aws-profile
97+
```
98+
99+
---
100+
101+
## 📝 Notes
102+
103+
* This deployment is **not hardened for production** — it’s suitable for short-term testing and evaluation.
104+
* The EC2 instance is assigned a public IP and open security group (ports 22, 80, 443).
105+
* No NAT Gateway or private subnets are used — it’s a flat public deployment.
106+
107+
---
108+
109+
## 📎 License
110+
111+
MIT — © University of Oxford, 2025

‎odk-wrapper/README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# ODK Central Wrapper API
2+
3+
A lightweight TypeScript REST API for securely extracting, modifying, and returning encrypted submission data from an ODK Central instance.
4+
Built with Express and Zod, and featuring OpenAPI/Swagger documentation for immediate testability.
5+
6+
---
7+
8+
## ✨ Features
9+
10+
- Fetches and decrypts submission data from ODK Central
11+
- Normalizes `idFieldId` to use ODK Central’s internal UUID (`KEY`)
12+
- Removes unwanted fields from export
13+
- Returns a cleaned-up `.zip` archive of the submission CSV
14+
- OpenAPI (Swagger) docs with interactive "Try it out" support
15+
16+
---
17+
18+
## 🚀 Quick Start
19+
20+
### Prerequisites
21+
22+
- Node.js ≥ 16
23+
- npm
24+
25+
### Installation
26+
27+
```bash
28+
git clone https://github.com/OxfordRSE/ib-odk-wrapper.git
29+
cd odk-wrapper
30+
npm install
31+
````
32+
33+
### Development Mode
34+
35+
```bash
36+
npm run dev
37+
```
38+
39+
### Production Build
40+
41+
```bash
42+
npm run build
43+
npm start
44+
```
45+
46+
---
47+
48+
## 📡 API Usage
49+
50+
### Endpoint
51+
52+
```
53+
POST /
54+
```
55+
56+
### Body Parameters (JSON)
57+
58+
| Field | Type | Required | Description |
59+
|------------------|-------------------------|----------|---------------------------------------------------------|
60+
| `odkCentralUrl` | `string (URL)` | ✅ | The URL of your ODK Central instance |
61+
| `email` | `string (email)` | ✅ | Your ODK Central login email |
62+
| `password` | `string` | ✅ | Your ODK Central password |
63+
| `projectId` | `number` | ✅ | Project ID |
64+
| `formName` | `string` | ✅ | The `xmlFormId` of the form |
65+
| `decryptionKeys` | `Record<number,string>` | ✅ | Map of encryption key IDs to passwords |
66+
| `idFieldId` | `string` | ✅ | Id of the field used to link submissions longitudinally |
67+
| `dropFieldIds` | `string[]` (optional) | ❌ | Ids of fields to omit from the returned dataset |
68+
69+
---
70+
71+
## 📖 Documentation
72+
73+
Interactive Swagger UI is available at:
74+
75+
```
76+
http://localhost:3000/docs
77+
```
78+
79+
Use this to explore and test the API directly from your browser using real values.
80+
81+
---
82+
83+
## 📦 What It Does Internally
84+
85+
1. Authenticates with ODK Central and retrieves a session token
86+
2. Downloads a `.zip` of submission data for the given form
87+
3. Extracts the CSV and parses all submissions
88+
4. Normalizes the `idFieldId` using ODK Central’s `KEY` UUID
89+
5. Removes any specified fields (`dropFieldIds`)
90+
6. Re-zips the data and returns it in the response
91+
7. Cleans up temporary files
92+
93+
---
94+
95+
## 🔐 Security Notes
96+
97+
* All decryption happens in memory; no credentials or secrets are persisted
98+
* Temporary files are deleted as soon as the response is complete
99+
100+
---
101+
102+
## 🛠 Troubleshooting
103+
104+
Errors will return a JSON object with `error` and `parent` fields.
105+
The `error` field contains a human-readable message, while `parent` provides the original error object for debugging.
106+
Because this is a thin wrapper API, the full error stack can be returned to the client for easier debugging.
107+
108+
---
109+
110+
## 📄 License
111+
112+
MIT — free to use, modify, and distribute.
113+

‎odk-wrapper/package.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
"private": true,
2424
"repository": {
2525
"type": "git",
26-
"url": "git+https://github.com/OxfordRSE/odk-wrapper.git"
26+
"url": "git+https://github.com/OxfordRSE/ib-odk-wrapper.git"
2727
},
2828
"keywords": [
2929
"ODK",
@@ -32,9 +32,9 @@
3232
"author": "Matt Jaquiery",
3333
"license": "MIT",
3434
"bugs": {
35-
"url": "https://github.com/OxfordRSE/odk-wrapper/issues"
35+
"url": "https://github.com/OxfordRSE/ib-odk-wrapper/issues"
3636
},
37-
"homepage": "https://github.com/OxfordRSE/odk-wrapper#readme",
37+
"homepage": "https://github.com/OxfordRSE/ib-odk-wrapper#readme",
3838
"dependencies": {
3939
"archiver": "^7.0.1",
4040
"axios": "^1.10.0",

0 commit comments

Comments
 (0)