Skip to content

Commit b3df754

Browse files
author
Lasim
committed
Enhance email logging, add OAuth implementation guide, improve plugin logging, clarify roles and permissions, and provide detailed database setup instructions for self-hosting DeployStack.
1 parent 0eeab70 commit b3df754

17 files changed

Lines changed: 3554 additions & 149 deletions

‎docs/deploystack/auth.mdx‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: Authentication Methods
3+
description: Available authentication methods in DeployStack, including email registration and GitHub OAuth, with configuration instructions for administrators.
4+
---
5+
6+
# Authentication Methods
7+
8+
DeployStack supports multiple authentication methods to provide flexibility for different user preferences and organizational requirements. This document outlines the available authentication options and how to configure them.
9+
10+
## Available Authentication Methods
11+
12+
### Email Registration & Login
13+
14+
Email-based authentication is the primary authentication method in DeployStack. Users can register with their email address and password, and subsequently log in using these credentials.
15+
16+
**Features:**
17+
- Secure password hashing using Argon2
18+
- Email verification (when email sending is enabled)
19+
- Password reset functionality
20+
- Profile management
21+
22+
**User Experience:**
23+
1. Users register with email, password, and optional personal information
24+
2. Email verification may be required (depending on configuration)
25+
3. Users can log in using email or username
26+
4. Password reset available via email (when email sending is enabled)
27+
28+
### GitHub OAuth
29+
30+
GitHub OAuth provides a convenient way for users to authenticate using their existing GitHub accounts. This method is particularly useful for development teams and organizations already using GitHub.
31+
32+
**Features:**
33+
- Single sign-on with GitHub
34+
- Automatic email verification (GitHub emails are considered verified)
35+
- Profile information imported from GitHub
36+
- Secure OAuth 2.0 flow
37+
38+
**User Experience:**
39+
1. Users click "Login with GitHub" button
40+
2. Redirected to GitHub for authorization
41+
3. Upon approval, automatically logged into DeployStack
42+
4. Profile information (name, email) imported from GitHub
43+
44+
## Authentication Configuration
45+
46+
### Global Authentication Settings
47+
48+
Administrators can control authentication behavior through global settings:
49+
50+
| Setting | Description | Default |
51+
|---------|-------------|---------|
52+
| **Enable Login** | Master switch for all authentication methods | `true` |
53+
| **Enable Email Registration** | Allow new users to register via email | `true` |
54+
| **GitHub OAuth Enabled** | Enable GitHub OAuth authentication | `false` |
55+
56+
### Email Authentication Configuration
57+
58+
Email authentication is always available but requires SMTP configuration for full functionality:
59+
60+
**Required for Full Functionality:**
61+
- SMTP server configuration (for email verification and password reset)
62+
- Email sending enabled in global settings
63+
64+
**Configuration Steps:**
65+
1. Navigate to **Global Settings** → **SMTP Mail Settings**
66+
2. Configure SMTP server details:
67+
- Host (e.g., `smtp.gmail.com`)
68+
- Port (e.g., `587`)
69+
- Username and Password
70+
- Security settings
71+
3. Enable email sending in **Global Settings** → **Global Configuration**
72+
73+
### GitHub OAuth Configuration
74+
75+
GitHub OAuth requires setup both in GitHub and DeployStack:
76+
77+
**GitHub Setup:**
78+
1. Go to GitHub → Settings → Developer settings → OAuth Apps
79+
2. Create a new OAuth App with:
80+
- **Application name**: Your DeployStack instance name
81+
- **Homepage URL**: Your DeployStack frontend URL
82+
- **Authorization callback URL**: `https://your-domain.com/api/auth/github/callback`
83+
3. Note the **Client ID** and **Client Secret**
84+
85+
**DeployStack Configuration:**
86+
1. Navigate to **Global Settings** → **GitHub OAuth Configuration**
87+
2. Configure the following settings:
88+
- **Client ID**: From your GitHub OAuth App
89+
- **Client Secret**: From your GitHub OAuth App (encrypted)
90+
- **Enabled**: Set to `true` to activate GitHub OAuth
91+
- **Callback URL**: Must match the URL configured in GitHub
92+
- **Scope**: OAuth permissions (default: `user:email`)
93+
94+
**Configuration Example:**
95+
```
96+
Client ID: abc123def456
97+
Client Secret: [encrypted]
98+
Enabled: true
99+
Callback URL: https://your-deploystack.com/api/auth/github/callback
100+
Scope: user:email
101+
```
102+
103+
## User Roles and First User
104+
105+
### First User (Global Administrator)
106+
107+
The first user registered in DeployStack automatically becomes the **Global Administrator** with full system access. This ensures there's always at least one administrator who can manage the system.
108+
109+
**Important Notes:**
110+
- The first user **must** be created via email registration
111+
- GitHub OAuth cannot be used to create the first user
112+
- This prevents accidental creation of admin accounts via OAuth
113+
114+
### Subsequent Users
115+
116+
All users registered after the first user receive the **Global User** role by default, regardless of authentication method used.
117+
118+
**Role Assignment:**
119+
- **Email Registration**: `global_user` role
120+
- **GitHub OAuth**: `global_user` role
121+
- **Role Changes**: Only global administrators can modify user roles
122+
123+
## Security Considerations
124+
125+
### Email Authentication Security
126+
127+
- Passwords are hashed using Argon2 with secure parameters
128+
- Email verification prevents unauthorized account creation
129+
- Password reset tokens are time-limited and single-use
130+
- Session management handled by Lucia v3
131+
132+
### GitHub OAuth Security
133+
134+
- OAuth 2.0 standard with state parameter for CSRF protection
135+
- GitHub emails are considered verified
136+
- Secure token exchange and validation
137+
- No GitHub credentials stored in DeployStack
138+
139+
### Account Linking
140+
141+
When a user with an existing email account uses GitHub OAuth with the same email address:
142+
- The GitHub account is automatically linked to the existing account
143+
- User can subsequently use either authentication method
144+
- No duplicate accounts are created
145+
146+
## Troubleshooting
147+
148+
### Email Authentication Issues
149+
150+
**Email verification not working:**
151+
- Check SMTP configuration in Global Settings
152+
- Verify email sending is enabled
153+
- Check server logs for email delivery errors
154+
155+
**Password reset not working:**
156+
- Ensure SMTP is configured and email sending is enabled
157+
- Verify the reset link hasn't expired (tokens are time-limited)
158+
159+
### GitHub OAuth Issues
160+
161+
**"GitHub OAuth is not enabled" error:**
162+
- Check that GitHub OAuth is enabled in Global Settings
163+
- Verify Client ID and Client Secret are configured
164+
- Ensure callback URL matches GitHub OAuth App configuration
165+
166+
**"GitHub email not available" error:**
167+
- User's GitHub email must be public and verified
168+
- Check GitHub account email settings
169+
- Ensure OAuth scope includes `user:email`
170+
171+
**First user creation blocked:**
172+
- This is expected behavior - first user must use email registration
173+
- Use email registration to create the initial administrator account
174+
175+
### General Authentication Issues
176+
177+
**Login disabled:**
178+
- Check that "Enable Login" is set to `true` in Global Settings
179+
- Verify database is properly configured and accessible
180+
181+
**Registration disabled:**
182+
- Check that "Enable Email Registration" is set to `true` for email signup
183+
- Verify GitHub OAuth is enabled and configured for GitHub login
184+
185+
## API Endpoints
186+
187+
For developers and integrations, DeployStack provides REST API endpoints for authentication:
188+
189+
### Email Authentication
190+
- `POST /api/auth/email/register` - User registration
191+
- `POST /api/auth/email/login` - User login
192+
- `POST /api/auth/email/forgot-password` - Password reset request
193+
- `POST /api/auth/email/reset-password` - Password reset confirmation
194+
195+
### GitHub OAuth
196+
- `GET /api/auth/github/login` - Initiate GitHub OAuth flow
197+
- `GET /api/auth/github/callback` - OAuth callback handler
198+
- `GET /api/auth/github/status` - Check if GitHub OAuth is enabled
199+
200+
### General Authentication
201+
- `POST /api/auth/logout` - User logout
202+
- `GET /api/users/me` - Get current user profile
203+
- `PUT /api/auth/profile/update` - Update user profile
204+
205+
## Best Practices
206+
207+
### For Administrators
208+
209+
1. **Always configure the first user via email** to ensure proper admin access
210+
2. **Set up SMTP early** to enable email verification and password reset
211+
3. **Use strong OAuth secrets** and keep them secure
212+
4. **Regularly review user accounts** and roles
213+
5. **Monitor authentication logs** for security issues
214+
215+
### For Users
216+
217+
1. **Use strong passwords** for email authentication
218+
2. **Verify your email address** when using email registration
219+
3. **Keep GitHub account secure** when using OAuth
220+
4. **Use the same email address** across authentication methods for account linking
221+
222+
### For Organizations
223+
224+
1. **Choose authentication methods** that align with your security policies
225+
2. **Consider GitHub OAuth** for development teams already using GitHub
226+
3. **Implement proper access controls** through user roles
227+
4. **Document authentication procedures** for your team
228+
5. **Plan for account recovery** scenarios
229+
230+
---
231+
232+
For technical implementation details, see the [Backend Authentication Documentation](/deploystack/development/backend/api) and [Global Settings Management](/deploystack/global-settings).

‎docs/deploystack/development/backend/api.mdx‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,127 @@ When the server is running (`npm run dev`), you can access:
8989
4. Select the generated `api-spec.json` file
9090
5. All API endpoints will be imported with proper documentation
9191

92+
## Route File Structure Rules
93+
94+
**IMPORTANT**: Every new API endpoint must be created in a separate file following the established directory structure pattern. Do not add route definitions directly to `src/routes/index.ts`.
95+
96+
### File Structure Requirements
97+
98+
1. **Separate Files**: Each route or group of related routes must be in its own file
99+
2. **Directory Organization**: Group related routes in directories (e.g., `/auth/`, `/users/`, `/health/`)
100+
3. **Import Pattern**: Routes are imported and registered in `src/routes/index.ts`
101+
4. **Consistent Naming**: Use descriptive names that match the route purpose
102+
103+
### Correct File Structure
104+
105+
```
106+
services/backend/src/routes/
107+
├── index.ts # Main routes registration (imports only)
108+
├── health/
109+
│ └── index.ts # Health check endpoints
110+
├── auth/
111+
│ ├── loginEmail.ts # Email login endpoint
112+
│ ├── registerEmail.ts # Email registration endpoint
113+
│ └── logout.ts # Logout endpoint
114+
├── db/
115+
│ ├── status.ts # Database status endpoint
116+
│ └── setup.ts # Database setup endpoint
117+
├── users/
118+
│ └── index.ts # User management endpoints
119+
└── teams/
120+
└── index.ts # Team management endpoints
121+
```
122+
123+
### Route File Template
124+
125+
Each route file should follow this pattern:
126+
127+
```typescript
128+
import { type FastifyInstance } from 'fastify'
129+
import { z } from 'zod'
130+
import { zodToJsonSchema } from 'zod-to-json-schema'
131+
132+
// Define your schemas
133+
const responseSchema = z.object({
134+
// Your response structure
135+
});
136+
137+
export default async function yourRoute(server: FastifyInstance) {
138+
server.get('/your-endpoint', {
139+
schema: {
140+
tags: ['Your Category'],
141+
summary: 'Brief description',
142+
description: 'Detailed description',
143+
response: {
144+
200: zodToJsonSchema(responseSchema, {
145+
$refStrategy: 'none',
146+
target: 'openApi3'
147+
})
148+
}
149+
}
150+
}, async () => {
151+
// Your route logic
152+
return { /* your response */ }
153+
});
154+
}
155+
```
156+
157+
### Registration in index.ts
158+
159+
Import and register your route in `src/routes/index.ts`:
160+
161+
```typescript
162+
// Import your route
163+
import yourRoute from './your-directory'
164+
165+
export const registerRoutes = (server: FastifyInstance): void => {
166+
server.register(async (apiInstance) => {
167+
// Register your route
168+
await apiInstance.register(yourRoute);
169+
170+
// Other route registrations...
171+
}, { prefix: '/api' });
172+
}
173+
```
174+
175+
### ❌ What NOT to Do
176+
177+
```typescript
178+
// DON'T: Add routes directly to index.ts
179+
export const registerRoutes = (server: FastifyInstance): void => {
180+
server.register(async (apiInstance) => {
181+
// ❌ BAD: Inline route definition
182+
apiInstance.get('/my-endpoint', {
183+
schema: { /* ... */ }
184+
}, async () => {
185+
return { message: 'This should be in a separate file!' }
186+
});
187+
}, { prefix: '/api' });
188+
}
189+
```
190+
191+
### ✅ What TO Do
192+
193+
```typescript
194+
// ✅ GOOD: Import and register separate route files
195+
import myEndpointRoute from './my-endpoint'
196+
197+
export const registerRoutes = (server: FastifyInstance): void => {
198+
server.register(async (apiInstance) => {
199+
// ✅ GOOD: Register imported route
200+
await apiInstance.register(myEndpointRoute);
201+
}, { prefix: '/api' });
202+
}
203+
```
204+
205+
### Benefits of This Structure
206+
207+
1. **Maintainability**: Each endpoint is self-contained and easy to find
208+
2. **Scalability**: Adding new endpoints doesn't clutter the main routes file
209+
3. **Testing**: Individual route files can be tested in isolation
210+
4. **Code Organization**: Related functionality is grouped together
211+
5. **Team Collaboration**: Multiple developers can work on different routes without conflicts
212+
92213
## Adding Documentation to Routes
93214

94215
To add OpenAPI documentation to your routes, define your request body and response schemas using Zod. Then, use the `zodToJsonSchema` utility to convert these Zod schemas into the JSON Schema format expected by Fastify.

0 commit comments

Comments
 (0)