Initial commit: Open sourcing all of the Maple Open Technologies code.
This commit is contained in:
commit
755d54a99d
2010 changed files with 448675 additions and 0 deletions
333
cloud/maplepress-backend/docs/GETTING-STARTED.md
Normal file
333
cloud/maplepress-backend/docs/GETTING-STARTED.md
Normal file
|
|
@ -0,0 +1,333 @@
|
|||
# MaplePress Backend - Getting Started
|
||||
|
||||
Complete guide for local development in under 5 minutes.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker and Docker Compose installed
|
||||
- Go 1.21+ installed
|
||||
- Task (Taskfile) installed: `brew install go-task/tap/go-task`
|
||||
|
||||
### Start Development (3 steps)
|
||||
|
||||
```bash
|
||||
# 1. Start infrastructure (in separate terminal)
|
||||
cd ../infrastructure/development
|
||||
task dev:start
|
||||
# Wait ~1 minute for services to be ready
|
||||
|
||||
# 2. Start backend (in this directory)
|
||||
cd ../maplepress-backend
|
||||
task dev
|
||||
# Backend runs at http://localhost:8000
|
||||
# Press Ctrl+C to stop
|
||||
# Auto-migration and hot-reload are enabled
|
||||
|
||||
# 3. Verify it's running
|
||||
curl http://localhost:8000/health
|
||||
# Should return: {"status":"healthy"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create Test Data
|
||||
|
||||
### 1. Register a User
|
||||
|
||||
```bash
|
||||
# Create user and tenant
|
||||
curl -X POST http://localhost:8000/api/v1/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "test@example.com",
|
||||
"password": "TestPassword123!",
|
||||
"name": "Test User",
|
||||
"tenant_name": "Test Organization",
|
||||
"tenant_slug": "test-org"
|
||||
}'
|
||||
```
|
||||
|
||||
**Save the `access_token` from the response!**
|
||||
|
||||
```bash
|
||||
# Export your token for subsequent requests
|
||||
export TOKEN="eyJhbGci..."
|
||||
```
|
||||
|
||||
### 2. Create a WordPress Site
|
||||
|
||||
```bash
|
||||
# Tenant is automatically determined from JWT token
|
||||
curl -X POST http://localhost:8000/api/v1/sites \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: JWT $TOKEN" \
|
||||
-d '{
|
||||
"domain": "localhost:8081",
|
||||
"site_url": "http://localhost:8081"
|
||||
}'
|
||||
```
|
||||
|
||||
**Save the `api_key` from the response!** (Shown only once)
|
||||
|
||||
### 3. Test Plugin Authentication
|
||||
|
||||
```bash
|
||||
# Test the API key (what WordPress plugin uses)
|
||||
curl -X GET http://localhost:8000/api/v1/plugin/status \
|
||||
-H "Authorization: Bearer YOUR_API_KEY_HERE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Start backend (foreground, see logs)
|
||||
task dev
|
||||
|
||||
# Restart after code changes
|
||||
# CompileDaemon auto-rebuilds on file changes
|
||||
# Only manually restart if needed:
|
||||
# Press Ctrl+C, then:
|
||||
task dev
|
||||
|
||||
# Stop backend
|
||||
# Press Ctrl+C (or task dev:down in another terminal)
|
||||
```
|
||||
|
||||
### Database
|
||||
|
||||
```bash
|
||||
# Clear database (WARNING: deletes all data!)
|
||||
task db:clear
|
||||
|
||||
# Manual migration (only if auto-migrate disabled)
|
||||
task migrate:up
|
||||
|
||||
# View database
|
||||
cd ../infrastructure/development
|
||||
task cql
|
||||
# Inside cqlsh:
|
||||
USE maplepress;
|
||||
SELECT * FROM sites_by_id;
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
task test
|
||||
|
||||
# Format code
|
||||
task format
|
||||
|
||||
# Run linters
|
||||
task lint
|
||||
```
|
||||
|
||||
### API Operations
|
||||
|
||||
```bash
|
||||
# Export your token first
|
||||
export TOKEN="your_jwt_token_here"
|
||||
|
||||
# Get your profile
|
||||
curl http://localhost:8000/api/v1/me \
|
||||
-H "Authorization: JWT $TOKEN"
|
||||
|
||||
# List sites
|
||||
curl http://localhost:8000/api/v1/sites \
|
||||
-H "Authorization: JWT $TOKEN"
|
||||
|
||||
# Get specific site
|
||||
curl http://localhost:8000/api/v1/sites/SITE_ID \
|
||||
-H "Authorization: JWT $TOKEN"
|
||||
|
||||
# Delete site
|
||||
curl -X DELETE http://localhost:8000/api/v1/sites/SITE_ID \
|
||||
-H "Authorization: JWT $TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WordPress Plugin Setup
|
||||
|
||||
### 1. Access WordPress Admin
|
||||
|
||||
```bash
|
||||
# WordPress is running at:
|
||||
http://localhost:8081/wp-admin
|
||||
# Default credentials: admin / admin
|
||||
```
|
||||
|
||||
### 2. Configure MaplePress Plugin
|
||||
|
||||
1. Navigate to **Settings → MaplePress**
|
||||
2. Enter:
|
||||
- **API URL**: `http://maplepress-backend-dev:8000`
|
||||
- **API Key**: Your site API key from step 2 above
|
||||
3. Click **Save Settings & Verify Connection**
|
||||
|
||||
**Note**: Use `http://maplepress-backend-dev:8000` (not `localhost`) because WordPress runs in Docker and needs the container name.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Backend won't start
|
||||
|
||||
**Error**: "Infrastructure not running!"
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
cd ../infrastructure/development
|
||||
task dev:start
|
||||
# Wait for services to be healthy (~1 minute)
|
||||
```
|
||||
|
||||
### Token expired (401 Unauthorized)
|
||||
|
||||
Tokens expire after 60 minutes. Login again:
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/v1/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "test@example.com",
|
||||
"password": "TestPassword123!"
|
||||
}'
|
||||
```
|
||||
|
||||
### WordPress can't connect to backend
|
||||
|
||||
**Error**: "Could not resolve host"
|
||||
|
||||
**Solution**: Make sure you're using `http://maplepress-backend-dev:8000` (not `localhost:8000`) in WordPress settings.
|
||||
|
||||
**Verify from WordPress container**:
|
||||
```bash
|
||||
docker exec maple-wordpress-dev curl http://maplepress-backend-dev:8000/health
|
||||
# Should return: {"status":"healthy"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Backend (Port 8000)
|
||||
├── HTTP Server
|
||||
├── JWT Authentication (user access)
|
||||
├── API Key Authentication (plugin access)
|
||||
├── Domain Layer (business logic)
|
||||
├── Repository Layer (data access)
|
||||
└── Infrastructure
|
||||
├── Cassandra (primary database)
|
||||
├── Redis (caching)
|
||||
├── Meilisearch (search indexing)
|
||||
└── SeaweedFS (S3-compatible storage)
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Tenant**: Organization/account that can have multiple users and sites
|
||||
- **User**: Person who logs in with email/password (gets JWT token)
|
||||
- **Site**: WordPress installation (gets API key for plugin authentication)
|
||||
- **Multi-tenancy**: All data is scoped to a tenant_id
|
||||
- **JWT Token**: Used by dashboard/admin users (Authorization: JWT ...)
|
||||
- **API Key**: Used by WordPress plugins (Authorization: Bearer ...)
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Public (No Auth)
|
||||
- `GET /health` - Health check
|
||||
- `POST /api/v1/register` - Register user + tenant
|
||||
- `POST /api/v1/login` - Login
|
||||
|
||||
### Authenticated (JWT Required)
|
||||
- `GET /api/v1/me` - Get user profile
|
||||
- `POST /api/v1/sites` - Create site
|
||||
- `GET /api/v1/sites` - List sites
|
||||
- `GET /api/v1/sites/{id}` - Get site
|
||||
- `DELETE /api/v1/sites/{id}` - Delete site
|
||||
- `POST /api/v1/sites/{id}/rotate-key` - Rotate API key
|
||||
|
||||
### Plugin (API Key Required)
|
||||
- `GET /api/v1/plugin/status` - Verify API key and get site info
|
||||
|
||||
**Full API documentation**: See `API.md`
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The backend uses `.env` for configuration. Copy from sample:
|
||||
|
||||
```bash
|
||||
cp .env.sample .env
|
||||
```
|
||||
|
||||
**Key variables**:
|
||||
|
||||
```bash
|
||||
# Application
|
||||
APP_JWT_SECRET=change-me-in-production
|
||||
SERVER_PORT=8000
|
||||
|
||||
# Database (Cassandra)
|
||||
DATABASE_HOSTS=localhost
|
||||
DATABASE_KEYSPACE=maplepress
|
||||
|
||||
# Cache (Redis)
|
||||
CACHE_HOST=localhost
|
||||
CACHE_PORT=6379
|
||||
```
|
||||
|
||||
For Docker development, the `docker-compose.dev.yml` sets these automatically.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **API Documentation**: See `API.md` for complete endpoint reference
|
||||
- **Architecture**: See `DEVELOPER_GUIDE.md` for code structure
|
||||
- **WordPress Plugin**: See `native/wordpress/maplepress-plugin/README.md`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Infrastructure
|
||||
cd ../infrastructure/development
|
||||
task dev:start # Start all services
|
||||
task dev:stop # Stop all services
|
||||
task cql # Open Cassandra shell
|
||||
|
||||
# Backend
|
||||
cd ../maplepress-backend
|
||||
task dev # Start backend (auto-migrate + hot-reload)
|
||||
task dev:down # Stop backend
|
||||
task db:clear # Clear database
|
||||
task test # Run tests
|
||||
task build # Build binary (only for manual operations)
|
||||
task migrate:up # Manual migration (only if needed)
|
||||
|
||||
# View infrastructure logs
|
||||
docker logs maple-cassandra-1-dev # Cassandra logs
|
||||
docker logs maple-redis-dev # Redis logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Happy coding!** 🚀
|
||||
|
||||
For questions or issues, see the full documentation or check the [GitHub repository](https://codeberg.org/mapleopentech/monorepo).
|
||||
Loading…
Add table
Add a link
Reference in a new issue