Getting Started with WEMAZU

Name: Wemazu
Author: Wemazu

🚀 Welcome to WEMAZU - Your deployment platform: connect a GitHub repository, then map any branch to a domain and server and deploy.

This guide will walk you through everything you need to know to get started with WEMAZU, from authentication to your first deployment.

⚠️ Connect GitHub first. You must connect GitHub and add a Personal Access Token (classic or fine-grained) before you can create a project. Without it, you cannot select a repository, so project creation is not possible. See Connect GitHub First (Required).

Authentication Flow
Connect GitHub First (Required)
Creating Your First Project
Configuring Your First Deployment
Understanding Environments
Auto-Deploy Overview

Authentication Flow

How WEMAZU Authentication Works

WEMAZU uses SIMEZU for all authentication. This means:

✅ You never see SIMEZU - All login forms stay in WEMAZU
✅ No redirects - Authentication happens "under water" via API calls
✅ Headless SSO - SIMEZU handles user management, roles, and permissions
✅ Token-based - Your SIMEZU access token is stored securely

Navigate to http://localhost/wemazu/login.

Note: If we go live, we will change all links to the wemazu.com domain.

Step 2: Enter Your Credentials

Enter your email and password in the WEMAZU login form. These credentials are verified against SIMEZU, not stored in WEMAZU.

Step 3: Authentication Flow

sequenceDiagram
    participant User
    participant WEMAZU Frontend
    participant WEMAZU Backend
    participant SIMEZU API
    
    User->>WEMAZU Frontend: Enter email/password
    WEMAZU Frontend->>WEMAZU Backend: POST /api/auth/login
    WEMAZU Backend->>SIMEZU API: POST /simezu/api/auth/login
    SIMEZU API-->>WEMAZU Backend: access_token + user data
    WEMAZU Backend-->>WEMAZU Frontend: token + processed user
    WEMAZU Frontend->>WEMAZU Frontend: Store token in localStorage
    WEMAZU Frontend->>User: Redirect to /dashboard

Step 4: Token Storage

After successful login, your token is stored in:

Primary: localStorage.getItem('simezu_access_token')
Fallback: Cookie accessToken (set by SIMEZU)
Backward compatibility: localStorage.getItem('wemazu_token')

💡 Note: Tokens are never stored in WEMAZU's database. All authentication is stateless and verified via SIMEZU API on each request.

If you're already logged into SIMEZU (have an accessToken cookie):

WEMAZU detects the cookie on page load
Checks your autologin preference via SIMEZU API
If enabled, automatically syncs your user data and redirects to dashboard
If disabled, shows the login form for manual entry

API Authentication

All protected API endpoints use token-based authentication:

Token Priority Order:

Cookie: $_COOKIE['accessToken']
Authorization header: Bearer {token}
Session: $_SESSION['simezu_access_token']
GET parameter: ?token=... (for debugging only)

Verification:

Every request verifies the token with SIMEZU API: GET /simezu/api/auth/me
If token is invalid or expired, you're redirected to login (stays in WEMAZU)

Connect GitHub First (Required)

You must connect GitHub and add a Personal Access Token before you can create a project. WEMAZU uses your token to list your repositories so you can select one when creating a project. Without a connected GitHub account, you cannot choose a repository and therefore cannot create a project.

Why This Comes First

✅ Select a repository: The "New Project" flow lets you pick a repository from a list—that list comes from the GitHub API using your token.
✅ Branches and commits: After a project exists, WEMAZU uses the same token to fetch branches and commit history.
✅ Deployments: FTP/SFTP deployments download repository archives from GitHub; SSH/VPS deployments use the token for Git access.
✅ Webhooks: For auto-deploy, WEMAZU creates repository webhooks using your token.

Token Types: Classic or Fine-Grained

GitHub offers two kinds of Personal Access Tokens. You can use either:

	Classic token	Fine-grained token
Where	GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)	Same menu → Fine-grained tokens
Scope	Account-wide scopes (e.g. `repo`)	Per-repository or per-organization, with specific permissions
Best for	Simple setup, all your repos	Limiting access to only certain repositories

Option A: Classic Personal Access Token

On GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic).
Click "Generate new token (classic)".
Note: Give it a name (e.g. WEMAZU Deployment Token).
Expiration: Choose a duration or "No expiration".
Scopes:
- For private and public repos: check repo (Full control of private repositories).
- For public repos only: you can use public_repo instead.
Click "Generate token".
⚠️ Copy the token immediately—you won’t be able to see it again.

What WEMAZU uses it for: Reading repository list, branches, and commits; downloading repository archives (zip); creating and managing webhooks.

Option B: Fine-Grained Personal Access Token

On GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens.
Click "Generate new token".
Token name: e.g. WEMAZU Deployment.
Expiration: Choose as needed.
Resource owner: Your user or the organization that owns the repos you want to deploy.
Repository access: Either "All repositories" or "Only select repositories" (then pick the ones you’ll use in WEMAZU).

Permissions (Repository permissions):

Permission	Access	Why WEMAZU needs it
Contents	Read-only	Read repo and download archive (zip) for deployments
Metadata	Read-only	Repository info (required; often set by default)
Webhooks	Read and write	Create and manage webhooks for auto-deploy

Click "Generate token" and copy it. You won’t be able to see it again.

If you add more repos later: Edit the fine-grained token and add those repositories, or create a new token that includes them.

Add Your Token in WEMAZU

In the dashboard, click Settings in the sidebar, then GitHub Connection.
Paste your token (classic or fine-grained) in the "GitHub Personal Access Token" field.
Click "Connect GitHub" or "Save Token".

WEMAZU will:

✅ Validate the token with the GitHub API (GET /user).
✅ Encrypt and store it (AES-256-CBC; key from GITHUB_TOKEN_ENCRYPTION_KEY).
✅ Show your GitHub username when validation succeeds.

Your token is persistent: it is not removed on logout, session expiry, or project deletion. It is only removed if you click "Disconnect GitHub" in Settings and confirm.

⚠️ Webhooks on localhost: GitHub webhooks cannot use localhost URLs. For auto-deploy in production, set the WEBHOOK_PUBLIC_URL environment variable to your public WEMAZU URL.

Creating Your First Project

Prerequisite: You must have connected GitHub and added a Personal Access Token. Without that, you cannot select a repository and cannot create a project.

What is a Project?

A project in WEMAZU represents a connection between:

Your GitHub repository (we read its branches; we do not create branches)
Your deployment configuration (you choose which branch maps to which domain and server)

Step-by-Step: Create a New Project

1. Navigate to Projects

From the dashboard, click Projects in the sidebar (or go to /dashboard/repos).

2. Click "New Project"

Click the "New Project" button (usually in the top-right corner).

3. Select Your GitHub Repository

Because you connected GitHub first, WEMAZU can show your repositories. Choose the repository you want to deploy. You may also enter or adjust:

Project Name: A friendly name (e.g. "My Web App").
GitHub Owner and GitHub Repository: Usually pre-filled from your selection.

4. Submit and Wait

After clicking "Create Project":

✅ Project record is created in WEMAZU
✅ A webhook_secret is generated for GitHub webhooks (used for auto-deploy)
✅ The project appears in your projects list

WEMAZU does not create any Git branches. Your repository keeps its existing branches (e.g. main, develop). We read branches from GitHub; when you add a domain, you select which branch to deploy and map it to a server and deploy path. You can add as many such branch→domain/server mappings as you want.

You can now add servers and domains and run deployments.

Configuring Your First Deployment

Prerequisites

Before you can deploy, you need:

✅ GitHub connected (Personal Access Token—classic or fine-grained—added in Connect GitHub First)
✅ A project (created after connecting GitHub, so you could select a repository)
✅ A server (FTP, SFTP, or SSH/VPS)
✅ A domain (linked to your server)

Step 1: Add a Server

Servers represent your hosting infrastructure:

In the dashboard, click Servers in the sidebar.
Click "Add Server"
Fill in server details:

Server Types:

FTP (hosting or ftp): Traditional FTP hosting
- Host: Your FTP server hostname
- Port: Usually 21
- Username: Your FTP username
- Password: Your FTP password
- Deploy Path: Absolute path on server (e.g., /public_html)
SFTP (sftp): Secure FTP
- Host: Your SFTP server hostname
- Port: Usually 22
- Username: Your SFTP username
- Password: Your SFTP password (or use SSH key)
- Deploy Path: Absolute path on server
SSH/VPS (vps): Virtual Private Server with Git
- Host: Your server IP or hostname
- Port: Usually 22
- Username: Your SSH username
- Password: Your SSH password (or use SSH key)
- Deploy Path: Path to your Git repository (must already exist)

Click "Test Connection" to verify
Click "Save Server"

Step 2: Add a Domain

Domains link your project to a server and deployment path. WEMAZU reads branches from your GitHub repository; you do not create branches in WEMAZU—you select an existing branch and map it to a domain, server, and deploy path.

Open a project, then go to the Domains tab (or use Domains in the dashboard sidebar to manage all domains).
Click "Add Domain".
Fill in domain details:
- Domain Name: Your domain (e.g. example.com or staging.example.com).
- For each deployment target, add one or more branch rows:
  - Branch: Select a branch from the list (branches are read from GitHub; you can add as many branch rows as you want).
  - Server: Select the server to deploy to.
  - Deploy Path: Absolute path on that server (e.g. /var/www/html or /public_html).
  - Auto-Deploy (optional): Enable to deploy automatically when code is pushed to that branch.
Click "Save Domain".

Step 3: Manual Deployment

Once your domain is configured, you can deploy manually:

Open your project and go to the Deployments tab.
Click "Deploy" or "Deploy Now"
Select:
- Domain: Which domain to deploy to
- Branch: Which branch to deploy (defaults to domain's configured branch)
- Commit: Which commit to deploy (defaults to latest)
Click "Start Deployment"

Deployment Process

When you trigger a deployment, WEMAZU:

Queued → Deployment is created and queued
Building → Deployment status updates to "building"
Executing → Actual deployment happens:
- FTP/SFTP: Downloads repository archive from GitHub, extracts, uploads files
- SSH/VPS: Runs git fetch, git checkout {branch}, git pull origin {branch}
Success/Failed → Final status based on outcome

You can monitor the deployment in real time in the project’s Deployments tab.

Understanding Branches and Domains

How Branches and Domains Work

WEMAZU does not create Git branches. Your repository has its own branches (e.g. main, develop, feature/x). We read the list of branches from GitHub. You then choose which branch to deploy and map it to a domain, a server, and a deploy path.

Branch: Comes from your GitHub repo (we only read it). You select which branch to deploy for each mapping.
Domain: The URL where the app is served (e.g. example.com, staging.example.com).
Server: The server that hosts the files (FTP, SFTP, or SSH/VPS).
Deploy path: The directory on that server where files are deployed.

You can add as many branch mappings as you want: e.g. one domain with one branch, or one domain with several branches (each with its own server/path), or several domains each with their own branch/server/path.

Example

Project: My Web App
├── Domain: staging.example.com
│   └── Branch: develop → Server A → /var/www/staging
├── Domain: example.com
│   └── Branch: main → Server B → /var/www/production
└── Domain: test.example.com
    └── Branch: feature/test → Server A → /var/www/test

You might call one setup "staging" and another "production" by convention; WEMAZU does not auto-create any fixed staging/production branches or environments. You decide which branch maps to which domain and server.

Auto-Deploy Overview

What is Auto-Deploy?

Auto-deploy automatically triggers deployments when you push code to GitHub. No manual intervention required!

How Auto-Deploy Works

1. GitHub Webhook Setup

When you enable auto-deploy for a domain branch, WEMAZU:

Creates a GitHub webhook (if WEBHOOK_PUBLIC_URL is configured)
Configures the webhook to listen for push events
Sets the webhook secret for security
Points the webhook to: {WEBHOOK_PUBLIC_URL}/backend/api/webhooks/github

2. Webhook Payload

When you push to GitHub, GitHub sends a webhook payload:

{
  "ref": "refs/heads/main",
  "repository": {
    "owner": {
      "name": "atypisch"
    },
    "name": "testdeploy"
  },
  "commits": [
    {
      "id": "abc123...",
      "message": "Update README",
      "timestamp": "2025-01-25T10:00:00Z"
    }
  ]
}

3. WEMAZU Processing

WEMAZU receives the webhook and:

✅ Validates the webhook signature (if secret is configured)
✅ Identifies the project (github_owner + github_repo)
✅ Finds domain branches with auto_deploy = true for the pushed branch
✅ Creates a deployment for each matching domain branch
✅ Executes the deployment automatically

Enabling Auto-Deploy

Open your project and go to the Domains tab (or use Domains in the dashboard).
Edit a domain or domain branch.
Toggle "Auto-Deploy" to ON.
Save.

Auto-Deploy Requirements

For auto-deploy to work, you need:

✅ GitHub token connected (for webhook creation)
✅ Public webhook URL (WEBHOOK_PUBLIC_URL environment variable)
✅ Domain branch with auto_deploy = true
✅ GitHub webhook created (WEMAZU attempts this automatically)

⚠️ Current Limitation: GitHub webhooks cannot be created on localhost. For local development, auto-deploy will not work. In production, ensure WEBHOOK_PUBLIC_URL is set to your public domain (e.g., https://wemazu.example.com).

Manual Deployment vs. Auto-Deploy

Feature	Manual Deployment	Auto-Deploy
Trigger	User clicks "Deploy"	Automatic on Git push
Branch Selection	User selects branch	Based on pushed branch
Commit Selection	User selects commit	Latest commit in push
Control	Full control	Automatic
Use Case	Testing, rollbacks	Continuous deployment

Next Steps

Now that you understand the basics:

✅ Connect GitHub (add a classic or fine-grained Personal Access Token in Settings)
✅ Create your first project (select your repository from the list)
✅ Add a server (FTP, SFTP, or SSH)
✅ Configure a domain with a deployment path
✅ Trigger your first manual deployment
✅ Enable auto-deploy (if you have a public webhook URL)

Additional Resources

📖 Deployment Model - Understand deployment lifecycle and rollbacks
📖 Environments & Domains - Map branches to domains and servers
📖 Logs & Monitoring - Monitor your deployments
📖 Security & Responsibility Boundaries - Understand security practices

Troubleshooting

"GitHub token not found" / "GitHub account not connected"

Problem: WEMAZU cannot access your GitHub repository or you cannot select a repository when creating a project.

Solution:

In the dashboard, go to Settings → GitHub Connection.
Verify your token is connected.
If not, add a Personal Access Token:
- Classic: Create a token with repo (or public_repo for public repos only) at GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic).
- Fine-grained: Create a token with Contents (Read), Metadata (Read), and Webhooks (Read and write) for the repositories you use. See Connect GitHub First.

"Webhook not created"

Problem: Auto-deploy is not working because webhook creation failed.

Possible Causes:

WEMAZU is running on localhost (GitHub requires public URLs)
WEBHOOK_PUBLIC_URL environment variable is not set
GitHub token doesn't have repo scope