3DKenji

Self-hosted knowledge keeper for 3D printing projects

View the Project on GitHub bodybybuddha/3DKenji

Getting Started with 3DKenji

Get up and running with 3DKenji in minutes.

Contents

Installation

The fastest way to get started with all dependencies:

git clone https://github.com/yourusername/3dkenji.git
cd 3dkenji
docker-compose up

This starts:

Option 2: Local Development

If you prefer to run on your machine:

# Clone repository
git clone https://github.com/yourusername/3dkenji.git
cd 3dkenji

# Install dependencies (creates virtual environment)
make install

# Run development server
make dev

Server runs at http://localhost:8000.

Option 3: Devcontainer

For VS Code users:

  1. Open the repository in VS Code
  2. Click the “Reopen in Container” prompt
  3. Devcontainer automatically:
    • Creates Python virtual environment
    • Installs all dependencies
    • Starts PostgreSQL database - Bootstraps MCP tooling (GitHub, Postgres, Playwright, Chrome DevTools)
    • Sets up debugging
  4. If you need to rerun MCP setup manually:
make mcp-bootstrap

Your First Project

Step 1: Create a User Account

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "nickname": "alice-prints",
    "email": "alice@example.com",
    "password": "MySecurePassword123!",
    "display_name": "Alice Smith"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Important: Save the access_token – you’ll use it for all requests.

nickname is optional at registration, but recommended because it becomes your owner segment in project storage paths (Projects/<nickname>/<slug>).

Step 2: Create Your First Project

TOKEN="your-token-from-step-1"

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "Benchy Calibration",
    "description": "Calibration prints for printer tuning"
  }'

Response includes project id:

{
  "id": 1,
  "title": "Benchy Calibration",
  "description": "Calibration prints for printer tuning",
  "owner_id": "user_123",
  "created_at": "2026-02-21T10:30:45Z"
}

Step 3: Upload a Project File

Use the project ID from step 2:

curl -X POST http://localhost:8000/api/v1/projects/1/files/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/benchy.stl" \
  -F "path=models"

This same workflow also supports notes, images, CAD files, and other project assets. Point path at directories such as cad_files, images, or notes as needed.

Step 4: Browse Project Files

curl -X GET "http://localhost:8000/api/v1/projects/1/files?path=models" \
  -H "Authorization: Bearer $TOKEN"

Interactive API Documentation

3DKenji provides interactive Swagger UI for exploring the API:

  1. Start the server: make dev or docker-compose up
  2. Open browser: http://localhost:8000/docs
  3. Click “Authorize” and enter your token
  4. Try endpoints directly in the browser

Common Tasks

Change Your Password

curl -X POST http://localhost:8000/api/v1/auth/password-change \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "old_password": "MySecurePassword123!",
    "new_password": "NewSecurePassword456!"
  }'

Create an API Key for Automation

curl -X POST http://localhost:8000/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Home Assistant Integration"}'

Response (secret shown once):

{
  "id": "key_abc123",
  "name": "Home Assistant Integration",
  "created_at": "2026-02-21T10:30:45Z",
  "secret": "sk_live_abc123def456ghi789jkl..."
}

Use the secret in API requests:

curl -X GET http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer sk_live_abc123def456ghi789jkl..."

Update a Project

curl -X PATCH http://localhost:8000/api/v1/projects/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "Benchy Calibration Prints",
    "description": "Updated description"
  }'

Invite a Collaborator

curl -X POST http://localhost:8000/api/v1/projects/1/invitations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "email": "teammate@example.com",
    "role": "viewer",
    "expires_in_days": 7
  }'

The response includes an invitation token. The invitee can accept through /invitations/<token> in the UI or via API.

Delete a Project

Deletes the project and all its models:

curl -X DELETE http://localhost:8000/api/v1/projects/1 \
  -H "Authorization: Bearer $TOKEN"

File Upload Details

Supported File Types

File Size Limit

Maximum 10MB per file.

Upload Response

{
  "id": 1,
  "project_id": 1,
  "filename": "benchy.stl",
  "size_bytes": 1048576,
  "file_type": "application/vnd.ms-pmd",
  "storage_key": "projects/1/models/1/benchy.stl",
  "created_at": "2026-02-21T10:30:45Z",
  "tags": ["calibration", "benchmark"],
  "custom_metadata": {},
  "owner_id": "user_123"
}

Testing

Run the test suite:

make test

Tests verify:

Troubleshooting

Q: “Connection refused” error

Q: Postgres MCP does not start in VS Code

Q: “Port 8000 already in use”

# Find process on port 8000
lsof -i :8000

# Kill it
kill -9 <PID>

Q: CORS error when using from frontend

Q: File upload fails

Next Steps

Getting Help