Skip to content

Commit 4d690d4

Browse files
author
Dan Costello
committed
SST
1 parent 80c0936 commit 4d690d4

8 files changed

Lines changed: 12421 additions & 2498 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Deploy Docs Site
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
jobs:
12+
deploy:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v3
17+
18+
- name: Setup Node.js
19+
uses: actions/setup-node@v3
20+
with:
21+
node-version: '18'
22+
23+
- name: Setup pnpm
24+
uses: pnpm/action-setup@v2
25+
with:
26+
version: 8
27+
run_install: false
28+
29+
- name: Get pnpm store directory
30+
id: pnpm-cache
31+
shell: bash
32+
run: |
33+
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
34+
35+
- name: Setup pnpm cache
36+
uses: actions/cache@v3
37+
with:
38+
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
39+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
40+
restore-keys: |
41+
${{ runner.os }}-pnpm-store-
42+
43+
- name: Install dependencies
44+
working-directory: ./docs
45+
run: pnpm install
46+
47+
- name: Build Next.js site
48+
working-directory: ./docs
49+
run: pnpm build
50+
51+
- name: Configure AWS credentials
52+
if: github.ref == 'refs/heads/main'
53+
uses: aws-actions/configure-aws-credentials@v2
54+
with:
55+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
56+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
57+
aws-region: us-east-1
58+
59+
- name: Deploy to AWS with SST
60+
if: github.ref == 'refs/heads/main'
61+
working-directory: ./docs
62+
run: |
63+
npx sst deploy --stage prod
64+
env:
65+
# Add any environment variables needed for deployment
66+
DOMAIN: ${{ secrets.DOMAIN_NAME }}
67+
68+
- name: Deploy to AWS dev environment (for PRs)
69+
if: github.event_name == 'pull_request'
70+
working-directory: ./docs
71+
run: |
72+
npx sst deploy --stage pr-${{ github.event.pull_request.number }}
73+
env:
74+
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
75+
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

‎DEPLOYMENT.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Deploying the UserClouds Docs Site
2+
3+
This documentation explains how to deploy the UserClouds docs site to AWS using SST and GitHub Actions.
4+
5+
## Overview
6+
7+
This project uses:
8+
9+
- Next.js for the documentation site
10+
- SST for infrastructure as code
11+
- AWS services (S3, CloudFront, Lambda)
12+
- GitHub Actions for CI/CD
13+
14+
The site is primarily built statically with the `/api/search` endpoint running as a serverless function using Next.js API routes.
15+
16+
## Prerequisites
17+
18+
- Node.js 18 or later
19+
- pnpm
20+
- AWS account with appropriate credentials
21+
- GitHub repository access
22+
23+
## Configuration
24+
25+
### Environment Variables
26+
27+
Create a `.env` file (for local development) with the following variables:
28+
29+
```
30+
# AWS region for deployment
31+
REGION=us-east-1
32+
33+
# Optional: Custom domain name
34+
DOMAIN=yourdomain.com
35+
```
36+
37+
For GitHub Actions deployments, add these secrets to your repository:
38+
39+
- `AWS_ACCESS_KEY_ID`
40+
- `AWS_SECRET_ACCESS_KEY`
41+
- `DOMAIN_NAME` (optional)
42+
43+
### SST Configuration
44+
45+
The deployment uses `sst.config.ts` in the project root, which defines:
46+
47+
1. A Next.js site hosted on S3/CloudFront
48+
2. Configuration for serverless functions to handle API routes and dynamic content
49+
3. Any required resources (Buckets, etc.)
50+
51+
## Local Development
52+
53+
1. Install dependencies:
54+
55+
```bash
56+
pnpm install
57+
```
58+
59+
2. Run the development server:
60+
61+
```bash
62+
pnpm dev
63+
```
64+
65+
3. Test the SST deployment locally:
66+
```bash
67+
pnpm sst:dev
68+
```
69+
70+
## Deployment
71+
72+
### Manual Deployment
73+
74+
1. Build the Next.js site:
75+
76+
```bash
77+
pnpm build
78+
```
79+
80+
2. Deploy using SST:
81+
```bash
82+
pnpm sst:deploy --stage prod
83+
```
84+
85+
To remove the deployment:
86+
87+
```bash
88+
pnpm sst:remove --stage prod
89+
```
90+
91+
### GitHub Actions Deployment
92+
93+
The project includes a GitHub Actions workflow in `.github/workflows/deploy.yml` that:
94+
95+
1. Triggers on pushes to `main` and pull requests
96+
2. Installs dependencies
97+
3. Builds the Next.js site
98+
4. Deploys to AWS using SST
99+
100+
For main branch deployments, it uses the production stage. For pull requests, it creates a temporary stage named `pr-{PR_NUMBER}`.
101+
102+
## Architecture Details
103+
104+
### Static Assets
105+
106+
- Next.js static files are built using `pnpm build`
107+
- Static files are uploaded to an S3 bucket
108+
- CloudFront serves these files with appropriate caching
109+
110+
### API Endpoint
111+
112+
- The `/api/search` endpoint is implemented as a Next.js API route
113+
- The function is defined in `app/api/search/route.js` within the Next.js app
114+
- SST automatically deploys this route as a serverless function
115+
- The endpoint receives search queries and returns search results
116+
117+
### Custom Domain (Optional)
118+
119+
If a custom domain is provided:
120+
121+
- SSL certificate is automatically provisioned
122+
- CloudFront distribution uses the custom domain
123+
- DNS records are created (if using Route 53)
124+
125+
## Troubleshooting
126+
127+
### Common Issues
128+
129+
1. **Deployment fails with credential errors**
130+
131+
- Ensure AWS credentials are correctly set up
132+
- Check that the IAM user has appropriate permissions
133+
134+
2. **Custom domain not working**
135+
136+
- Verify that the domain is correctly configured in your DNS provider
137+
- Check that the SSL certificate has been validated
138+
139+
3. **API function timeout**
140+
- Increase the timeout setting for Next.js API routes in the SST configuration
141+
- Optimize the API route code for better performance
142+
- Consider implementing caching for frequently accessed search results
143+
144+
### Getting Help
145+
146+
If you encounter issues:
147+
148+
1. Check the CloudWatch logs for the Lambda functions
149+
2. Review the CloudFormation events in the AWS console
150+
3. Refer to the [SST documentation](https://docs.sst.dev/)
151+
152+
## Additional Resources
153+
154+
- [SST Documentation](https://docs.sst.dev/)
155+
- [Next.js Documentation](https://nextjs.org/docs)
156+
- [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/)

‎README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# UserClouds Documentation
2+
3+
This repository contains the official documentation for UserClouds products and services.
4+
5+
## Quick Start
6+
7+
### Prerequisites
8+
9+
- Node.js 18 or later
10+
- pnpm package manager
11+
12+
### Installation
13+
14+
```bash
15+
pnpm install
16+
```
17+
18+
### Development
19+
20+
Start the development server:
21+
22+
```bash
23+
pnpm dev
24+
```
25+
26+
Open [http://localhost:3000](http://localhost:3000) in your browser.
27+
28+
## Building and Deployment
29+
30+
### Local Production Build
31+
32+
```bash
33+
pnpm build
34+
pnpm serve
35+
```
36+
37+
### AWS Deployment
38+
39+
This project can be deployed to AWS using SST:
40+
41+
```bash
42+
# Development deployment
43+
pnpm sst:dev
44+
45+
# Production deployment
46+
pnpm sst:deploy
47+
48+
# Remove deployment
49+
pnpm sst:remove
50+
```
51+
52+
For more detailed deployment information, see [DEPLOYMENT.md](./DEPLOYMENT.md).
53+
54+
## Project Structure
55+
56+
```
57+
docs/
58+
├── app/ # Next.js application files
59+
├── content/ # Documentation content (Markdown/MDX)
60+
├── public/ # Static assets
61+
├── lib/ # Utility libraries
62+
├── scripts/ # Build scripts
63+
└── .source/ # Generated source files
64+
```
65+
66+
## Available Scripts
67+
68+
- `pnpm dev` - Start development server
69+
- `pnpm build` - Build production version
70+
- `pnpm serve` - Serve production build locally
71+
- `pnpm build:api` - Build OpenAPI documentation pages
72+
- `pnpm types:check` - Check TypeScript types
73+
- `pnpm clean` - Clean build artifacts
74+
75+
## License
76+
77+
Copyright © UserClouds, Inc. All rights reserved.

‎README.mdx‎

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎next.config.mjs‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,26 @@
1-
import { createMDX } from 'fumadocs-mdx/next';
1+
import { createMDX } from "fumadocs-mdx/next";
22

33
const withMDX = createMDX();
44

5-
const isDev = process.env.NODE_ENV === 'development';
5+
const isDev = process.env.NODE_ENV === "development";
66

77
/** @type {import('next').NextConfig} */
88
const config = {
99
reactStrictMode: true,
10-
output: 'export',
10+
output: "export",
11+
// Enable static exports for everything except the API route
12+
distDir: ".next",
13+
// Specify that the /api/search path needs server-side rendering
14+
// This will be handled by the Lambda function in SST
15+
experimental: {
16+
// This tells Next.js that API routes are handled externally
17+
externalDir: true,
18+
},
1119
images: {
1220
unoptimized: isDev,
13-
remotePatterns: [
14-
{
15-
hostname: 'files.readme.io',
16-
},
17-
],
1821
},
22+
// Ensure trailing slashes for better compatibility with S3/CloudFront
23+
trailingSlash: true,
1924
};
2025

2126
export default withMDX(config);

‎package.json‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@
1010
"clean": "rm -rf .next .source node_modules out pnpm-lock.yaml",
1111
"serve": "serve ./out",
1212
"types:check": "fumadocs-mdx && tsc --noEmit",
13-
"postinstall": "fumadocs-mdx"
13+
"postinstall": "fumadocs-mdx",
14+
"sst:dev": "sst dev",
15+
"sst:deploy": "sst deploy",
16+
"sst:remove": "sst remove"
1417
},
1518
"dependencies": {
1619
"ajv": "^8.17.1",
@@ -38,6 +41,11 @@
3841
"openapi-types": "^12.1.3",
3942
"postcss": "^8.5.3",
4043
"tailwindcss": "^4.1.8",
41-
"typescript": "^5.8.3"
44+
"typescript": "^5.8.3",
45+
"sst": "^2.39.7",
46+
"@aws-sdk/client-s3": "^3.427.0",
47+
"@aws-sdk/client-dynamodb": "^3.427.0",
48+
"aws-cdk-lib": "2.110.1",
49+
"constructs": "10.3.0"
4250
}
4351
}

0 commit comments

Comments
 (0)