Initial commit from template
Some checks failed
PROMPT_MANAGER Cloudflare Worker / Deploy to ${{ github.ref_name }} environment (push) Failing after 53s
Some checks failed
PROMPT_MANAGER Cloudflare Worker / Deploy to ${{ github.ref_name }} environment (push) Failing after 53s
This commit is contained in:
Harsh Gupta
208
README.md
Normal file
208
README.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# Cloudflare Worker API Template
|
||||
|
||||
A production-ready template for building secure, modular APIs with Cloudflare Workers, featuring built-in authentication, database integration, and comprehensive documentation.
|
||||
|
||||
## Features
|
||||
|
||||
- **Authentication & Authorization**: Pre-configured with API key and Bearer token authentication
|
||||
- **Database Integration**: Ready-to-use D1 database connections
|
||||
- **Storage**: R2 bucket integration for file storage
|
||||
- **Documentation**: Auto-generated Swagger/OpenAPI documentation
|
||||
- **CI/CD**: GitHub Actions workflows for automated deployments
|
||||
- **Environment Management**: Development, Playtest, and Production environments
|
||||
|
||||
## Design Documentation
|
||||
|
||||
All design documentation should be maintained in the blueprint repository:
|
||||
|
||||
1. Create design documentation in the blueprint repository located at `prompt-manager`
|
||||
2. Submit the design as a Pull Request to the blueprint repository
|
||||
3. Once approved, add the link to the design file in `docs/DESIGN.md`
|
||||
|
||||
The `docs/DESIGN.md` file should contain a reference to the design document's location in the blueprint repository.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Using This Template
|
||||
|
||||
1. **Checkout the template branch**:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
git checkout template
|
||||
```
|
||||
|
||||
2. **Replace placeholder variables**:
|
||||
Search and replace the following placeholders throughout the codebase:
|
||||
- `prompt-manager` - Your application name in lowercase (e.g., `my-api`)
|
||||
- `PROMPT_MANAGER` - Your application name in uppercase (e.g., `MY_API`)
|
||||
|
||||
Make sure to check all files, especially:
|
||||
- `wrangler.toml`
|
||||
- `.github/workflows/deploy.yaml`
|
||||
- `src/swagger/config.js`
|
||||
|
||||
3. **Set up a new Git repository**:
|
||||
```bash
|
||||
# Remove existing Git history
|
||||
rm -rf .git
|
||||
|
||||
# Initialize a new Git repository
|
||||
git init
|
||||
|
||||
# Add your remote repository
|
||||
git remote add origin <your-new-repository-url>
|
||||
|
||||
# Add all files
|
||||
git add .
|
||||
|
||||
# Commit
|
||||
git commit -m "Initial commit from template"
|
||||
|
||||
# Push to main branch
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
4. **Create development branches**:
|
||||
```bash
|
||||
# Create and push dev branch
|
||||
git checkout -b dev
|
||||
git push -u origin dev
|
||||
|
||||
# Create and push playtest branch
|
||||
git checkout -b playtest
|
||||
git push -u origin playtest
|
||||
```
|
||||
|
||||
## Branching Strategy
|
||||
|
||||
Follow this workflow for code changes:
|
||||
|
||||
1. **Feature Development**:
|
||||
- Create feature branches from `dev`
|
||||
- Name format: `feature/your-feature-name`
|
||||
|
||||
2. **Deployment Flow**:
|
||||
- **Playtest**: Merge directly from feature branches for testing
|
||||
- **Development**: Submit Pull Requests from feature branches
|
||||
- **Production**: Submit Pull Requests from `dev` to `main`
|
||||
|
||||
## Configuration
|
||||
|
||||
### Database (D1)
|
||||
|
||||
The template comes with D1 database configuration. If you need to use it:
|
||||
|
||||
1. Create your D1 databases for each environment:
|
||||
```bash
|
||||
create prompt-manager_dev
|
||||
create prompt-manager_playtest
|
||||
create prompt-manager_prod
|
||||
```
|
||||
|
||||
2. Update the database IDs in `wrangler.toml` with the IDs generated from the commands above.
|
||||
|
||||
If you don't need D1, remove the `d1_databases` sections from `wrangler.toml`.
|
||||
|
||||
### Storage (R2)
|
||||
|
||||
The template includes R2 bucket configuration. If you need to use it:
|
||||
|
||||
1. Create your R2 buckets for each environment:
|
||||
```bash
|
||||
create prompt-manager-dev
|
||||
create prompt-manager-playtest
|
||||
create prompt-manager-prod
|
||||
```
|
||||
|
||||
2. Update the bucket names in `wrangler.toml`.
|
||||
|
||||
If you don't need R2, remove the `r2_buckets` sections from `wrangler.toml`.
|
||||
|
||||
## Authentication
|
||||
|
||||
The API comes with two authentication methods:
|
||||
|
||||
1. **API Key Authentication**: Using the `X-Api-Key` header
|
||||
2. **Bearer Token Authentication**: Using the `Authorization: Bearer <token>` header
|
||||
|
||||
These are configured in the Swagger documentation and middleware. Do not modify the authentication mechanisms unless necessary.
|
||||
|
||||
## API Documentation
|
||||
|
||||
The API documentation is generated using Swagger/OpenAPI. The configuration is modular and located in:
|
||||
|
||||
- `src/swagger/config.js`: Main configuration
|
||||
- `src/swagger/endpoints/`: Individual endpoint definitions
|
||||
|
||||
When adding new endpoints:
|
||||
|
||||
1. Create a new file in `src/swagger/endpoints/` for your endpoint
|
||||
2. Export the endpoint configuration
|
||||
3. Import and add it to `src/swagger/config.js`
|
||||
|
||||
Access the documentation at `/api/prompt-manager/docs` when the API is running.
|
||||
|
||||
## Design Documentation
|
||||
|
||||
All design documentation should be maintained in the blueprint repository:
|
||||
|
||||
1. Create design documentation in the blueprint repository located at `prompt-manager`
|
||||
2. Submit the design as a Pull Request to the blueprint repository
|
||||
3. Once approved, add the link to the design file in `docs/DESIGN.md`
|
||||
|
||||
The `docs/DESIGN.md` file should contain a reference to the design document's location in the blueprint repository.
|
||||
|
||||
## Code Structure Guidelines
|
||||
|
||||
- Keep files modular and under 100 lines
|
||||
- Organize related functionality into separate modules
|
||||
- Place shared logic in `src/helpers/` or appropriate service directories
|
||||
- Follow the existing pattern for new endpoints and services
|
||||
|
||||
## Development
|
||||
|
||||
### Local Development
|
||||
|
||||
This project uses Docker for local development to ensure consistency across environments:
|
||||
|
||||
```bash
|
||||
# Start the local development server
|
||||
docker compose up
|
||||
|
||||
# To run in detached mode
|
||||
docker compose up -d
|
||||
|
||||
# To stop the server
|
||||
docker compose down
|
||||
```
|
||||
|
||||
The server will be available at http://localhost:8787.
|
||||
|
||||
### Deployment
|
||||
|
||||
Deployments are handled automatically by GitHub Actions when pushing to the appropriate branches:
|
||||
|
||||
- Push to `playtest` → Deploys to Playtest environment
|
||||
- Push to `dev` → Deploys to Development environment
|
||||
- Push to `main` → Deploys to Production environment
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
|
||||
## Development Checklist
|
||||
|
||||
Follow this checklist when working on a new feature or issue:
|
||||
|
||||
- [ ] Define Issue with Acceptance Criteria
|
||||
- [ ] Create one or more Tasks to Work on Issue
|
||||
- [ ] Create/Update Design Documentation
|
||||
- [ ] Create PR for Design Documentation
|
||||
- [ ] Follow Steps in README to create your own project
|
||||
- [ ] Commit Code and test default code in all 3 environments
|
||||
- [ ] Create feature branch for your issue
|
||||
- [ ] Write your own code
|
||||
- [ ] Test locally using docker compose
|
||||
- [ ] Merge to playtest branch
|
||||
- [ ] Test on Cloudflare
|
||||
- [ ] Request PR to dev branch
|
||||
Reference in New Issue
Block a user