Skip to content

Commit 44d7049

Browse files
committed
Fix template inconsistencies and enhance documentation
- Standardized on .template naming convention (removed config.env.example) - Made config.env.template generic with {{PROJECT_NAME}} placeholders - Added missing ECR_REPOSITORY and APP_RUNNER_SERVICE fields - Enhanced README.md with: - Prerequisites section (AWS setup, IAM roles, repository secrets) - justfile setup instructions - mxcp init --bootstrap for project initialization - Three clear data strategy options (static, downloaded, live API) - Fixed all file naming inconsistencies between template and documentation
1 parent ec1d8da commit 44d7049

File tree

3 files changed

+69
-20
lines changed

3 files changed

+69
-20
lines changed

README.md

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,22 @@ This repository provides standardized deployment infrastructure for MXCP project
2828
- `start.sh` - Generic container startup script
2929
- `requirements.txt` - Base MXCP dependencies
3030

31+
## Prerequisites
32+
33+
### AWS Setup
34+
1. **AWS Account** with App Runner service access
35+
2. **IAM Role**: `AppRunnerECRAccessRole` with ECR access permissions
36+
3. **Repository Secrets** in GitHub:
37+
- `AWS_ACCESS_KEY_ID` - For deployment access
38+
- `AWS_SECRET_ACCESS_KEY` - For deployment access
39+
- `MXCP_DATA_ACCESS_KEY_ID` - For data download (if needed)
40+
- `MXCP_DATA_SECRET_ACCESS_KEY` - For data download (if needed)
41+
42+
### Required Tools
43+
- **Git** - For repository management
44+
- **Docker** - For local testing (optional)
45+
- **just** - Modern task runner (optional but recommended)
46+
3147
## Usage
3248

3349
### For New MXCP Projects
@@ -54,7 +70,17 @@ vim deployment/config.env
5470
# APP_RUNNER_SERVICE=your-project-mxcp-server
5571
```
5672

57-
**3. Customize Docker Configuration**
73+
**3. Setup Task Runner (Optional but Recommended)**
74+
```bash
75+
# Copy and customize the modern task runner
76+
cp justfile.template justfile
77+
sed -i "s/{{PROJECT_NAME}}/your-project/g" justfile
78+
79+
# Install just (if not already installed)
80+
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin
81+
```
82+
83+
**4. Customize Docker Configuration**
5884
```bash
5985
# Update MXCP configuration
6086
cp deployment/mxcp-site-docker.yml.template deployment/mxcp-site-docker.yml
@@ -65,14 +91,45 @@ cp deployment/profiles-docker.yml.template deployment/profiles-docker.yml
6591
sed -i "s/{{PROJECT_NAME}}/your-project/g; s/{{AWS_REGION}}/your-region/g" deployment/profiles-docker.yml
6692
```
6793

68-
**4. Add Project-Specific Components**
94+
**5. Initialize MXCP Project Structure**
95+
```bash
96+
# Initialize MXCP project with example endpoints
97+
mxcp init --bootstrap
98+
99+
# This creates:
100+
# - mxcp-site.yml (main configuration)
101+
# - tools/ directory with example endpoints
102+
# - Basic project structure
103+
```
104+
105+
**6. Choose Your Data Strategy**
106+
107+
The template supports three data patterns:
108+
109+
**Option A: Static Data (simplest)**
110+
```bash
111+
# Place your data files in data/ directory
112+
mkdir -p data/
113+
# Copy your CSV/JSON files here
114+
# Modify Dockerfile to skip download step
115+
```
116+
117+
**Option B: Downloaded Data**
118+
```bash
119+
# Create data download script (customize for your source)
120+
mkdir -p scripts/
121+
# Create scripts/download_real_data.py for your data source (S3, API, etc.)
122+
# Docker will run this during build
123+
```
124+
125+
**Option C: Live API Integration**
69126
```bash
70-
# Add your project-specific directories
71-
mkdir -p tools/ models/ sql/ scripts/
72-
# Add your MXCP tools, dbt models, SQL queries, etc.
127+
# No data download needed - your tools connect to live APIs
128+
# Remove data download from Dockerfile
129+
# Configure API endpoints in your tools/
73130
```
74131

75-
**5. Deploy**
132+
**7. Deploy**
76133
```bash
77134
# Set GitHub repository secrets (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
78135
# Push to trigger automatic deployment

deployment/config.env.example

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

deployment/config.env.template

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# AWS Configuration for UAE MXCP Server
1+
# AWS Configuration for {{PROJECT_NAME}} MXCP Server
22
# Squirro: Customize these values for your environment
33

44
# AWS Account and Region
5-
AWS_ACCOUNT_ID=684130658470
5+
AWS_ACCOUNT_ID=YOUR_AWS_ACCOUNT_ID_HERE
66
AWS_REGION=eu-west-1
77

88
# Service Configuration
9-
ECR_REPOSITORY=uae-mxcp-server
10-
APP_RUNNER_SERVICE=uae-mxcp-server
9+
ECR_REPOSITORY={{PROJECT_NAME}}-mxcp-server
10+
APP_RUNNER_SERVICE={{PROJECT_NAME}}-mxcp-server
1111

1212
# Instance Configuration (App Runner)
13-
CPU_SIZE="4 vCPU"
14-
MEMORY_SIZE="8 GB"
13+
CPU_SIZE="0.5 vCPU"
14+
MEMORY_SIZE="2 GB"

0 commit comments

Comments
 (0)