1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244# Deployment Guide
This guide covers deploying Equalify to AWS infrastructure, including the frontend, backend API, and scanning services.
## Prerequisites
- AWS CLI v2 with SSO configured
- Node.js 18+ and Yarn
- AWS account with appropriate permissions
- Java 11+ (for PDF scanner)
## AWS SSO Setup
Configure AWS CLI for SSO access:
```bash
aws configure sso --profile equalifyuic
```
You'll be prompted for:
- **SSO session name**: `equalifyuic-sso`
- **SSO start URL**: `https://equalifyuic.awsapps.com/start`
- **SSO region**: `us-east-2`
- **CLI default region**: `us-east-2`
- **CLI output format**: `json`
To login for subsequent sessions:
```bash
aws sso login --profile equalifyuic
```
## Project Setup
Install all dependencies from the repository root:
```bash
cd equalify
yarn install
```
## Deploying the Frontend
The frontend deploys to S3 with CloudFront CDN.
### Build and Deploy to Staging
```bash
cd apps/frontend
yarn build:staging
```
This command:
1. Builds with Vite using staging environment variables
2. Syncs to S3 bucket `equalifyuic-web-staging`
3. Invalidates CloudFront distribution
### Build and Deploy to Production
```bash
yarn build:prod
```
This command:
1. Builds with Vite using production environment variables
2. Syncs to S3 bucket `equalifyuic-web`
3. Invalidates CloudFront distribution
### Deploy Both Environments
```bash
yarn build
```
## Deploying the Backend API
The backend deploys as a single Lambda function.
### Build and Deploy to Staging
```bash
cd apps/backend
yarn build:staging
```
This command:
1. Bundles with esbuild (excluding AWS SDK)
2. Creates `lambda.zip`
3. Updates Lambda function `equalifyuic-api-staging`
### Build and Deploy to Production
```bash
yarn build:prod
```
Updates Lambda function `equalifyuic-api`.
### Deploy Both Environments
```bash
yarn build
```
## Deploying Scanning Services
Each scanning service deploys independently.
### SQS Router
```bash
cd services/aws-lambda-scan-sqs-router
yarn build
```
### HTML Scanner
```bash
cd services/aws-lambda-scan-html
yarn build
```
### PDF Scanner (TypeScript)
```bash
cd services/aws-lambda-scan-pdf
yarn build
```
### PDF Scanner (Java/veraPDF)
```bash
cd services/aws-lambda-verapdf-interface
mvn package
# Deploy the resulting JAR to Lambda
```
## Environment Configuration
### Frontend Environment Variables
Create `.env.production` and `.env.staging` files:
```env
VITE_USERPOOLID=us-east-2_XXXXXXXX
VITE_USERPOOLWEBCLIENTID=XXXXXXXXXXXXXXXXXXXXXXXXXX
VITE_API_URL=https://api.equalifyapp.com
VITE_GRAPHQL_URL=https://graphql.equalifyapp.com
VITE_SSO_CLIENT_ID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
VITE_SSO_AUTHORITY=https://login.microsoftonline.com/TENANT_ID
```
### Backend Environment Variables
Configure in AWS Lambda:
| Variable | Description |
|----------|-------------|
| `DB_USER` | PostgreSQL username |
| `DB_HOST` | PostgreSQL host (RDS endpoint) |
| `DB_NAME` | Database name |
| `DB_PASSWORD` | Database password |
| `USER_POOL_ID` | Cognito User Pool ID |
| `WEB_CLIENT_ID` | Cognito Web Client ID |
| `SSO_ENABLED` | "true" to enable SSO |
| `WEBHOOKSECRET` | Hasura webhook secret |
### Scanner Environment Variables
| Variable | Description |
|----------|-------------|
| `RESULTS_ENDPOINT` | Webhook URL for results |
## AWS Infrastructure
### Required Resources
- **Lambda Functions**: API, SQS Router, HTML Scanner, PDF Scanner, veraPDF
- **SQS Queues**: `scanHtml.fifo`, `scanPdf.fifo`
- **S3 Buckets**: Frontend hosting (staging + production)
- **CloudFront**: CDN distributions
- **RDS**: PostgreSQL instance
- **Cognito**: User Pool for authentication
- **Hasura**: GraphQL engine (can be self-hosted or Hasura Cloud)
### Lambda Layers
The HTML scanner requires a Chromium layer. Use a pre-built layer:
- `@sparticuz/chromium` compatible layer
### SQS Configuration
FIFO queues with:
- Content-based deduplication: Disabled (using MessageDeduplicationId)
- Message group ID: `auditId` for ordered processing
- Visibility timeout: 5 minutes (for HTML scanner)
## Monitoring
### CloudWatch Logs
All Lambda functions log to CloudWatch:
- `/aws/lambda/equalifyuic-api`
- `/aws/lambda/equalifyuic-api-staging`
- `/aws/lambda/aws-lambda-scan-sqs-router`
- `/aws/lambda/aws-lambda-scan-html`
- `/aws/lambda/aws-lambda-scan-pdf`
### Lambda Powertools Metrics
Scanning services emit metrics:
- `scansStarted` - Count
- `ScanDuration` - Milliseconds
### Health Checks
Monitor:
- Lambda error rates
- SQS queue depth
- Database connections
- CloudFront error rates
## Troubleshooting
### Common Issues
**SSO Token Expired**
```bash
aws sso login --profile equalifyuic
```
**Lambda Deployment Fails**
- Ensure AWS CLI is authenticated
- Check Lambda function exists
- Verify IAM permissions
**Frontend Build Errors**
- Clear `node_modules` and reinstall
- Check environment variables are set
**Scan Timeouts**
- Increase Lambda timeout
- Check if pages are very large/slow
- Review CloudWatch logs for errors
### Logs
View recent logs:
```bash
aws logs tail /aws/lambda/equalifyuic-api --follow --profile equalifyuic
```
---
*For architecture details, see the Architecture Overview.*