Skip to content

Commit b867acb

Browse files
btouchardbtouchard
committed
feat: improve install script + installation readme
1 parent 32b469f commit b867acb

File tree

6 files changed

+1090
-59
lines changed

6 files changed

+1090
-59
lines changed

‎CHANGELOG.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,142 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [1.2.1] - 2025-11-05
9+
10+
### 🔐 Passwordless Authentication & Enhanced Installation
11+
12+
Minor release adding Magic Link authentication, improved metadata extraction, and professional installation tooling.
13+
14+
### Added
15+
16+
- **Magic Link Authentication (Passwordless)**
17+
- Email-based passwordless authentication system
18+
- No password required - users receive a secure link via email
19+
- Multi-method support: configure OAuth and/or MagicLink independently
20+
- Intelligent authentication method selection page
21+
- Auto-redirect to login when only one method is configured
22+
- Secure token generation with crypto/rand (32 bytes)
23+
- 15-minute expiration with automatic cleanup
24+
- HTML and text email templates for magic links
25+
- New migration `0012_magic_link_authentication` with `magic_links` table
26+
- Indexes on token, email, and expires_at for optimal performance
27+
- Background worker for cleaning expired magic links
28+
29+
- **Enhanced Installation Experience**
30+
- Interactive installation script with step-by-step guidance
31+
- Automatic environment detection (Docker, PostgreSQL, etc.)
32+
- System prerequisites validation
33+
- Assisted configuration of environment variables
34+
- Support for multi-authentication method setup
35+
- Complete installation documentation in `install/README.md`
36+
- Comprehensive `.env.example` with detailed comments
37+
- Docker Compose templates for quick deployment
38+
39+
- **E2E Testing with Cypress**
40+
- Complete end-to-end test suite for Magic Link authentication
41+
- MailHog integration for email testing in development
42+
- GitHub Actions workflow for automated E2E tests
43+
- Dedicated `compose.e2e.yml` for isolated test environment
44+
- Test utilities for email verification and link extraction
45+
46+
- **Smart Document Title Extraction**
47+
- Enhanced automatic title detection from HTML metadata
48+
- Support for Open Graph tags (`og:title`)
49+
- Support for Twitter Card tags (`twitter:title`)
50+
- Intelligent fallback hierarchy: OG → Twitter → title → h1
51+
- Comprehensive unit tests (233 test cases)
52+
- Better handling of edge cases and malformed HTML
53+
54+
### Changed
55+
56+
- **Architecture Improvements**
57+
- Refactored OAuth code into reusable `OAuthProvider` component
58+
- New `SessionService` for centralized session management
59+
- New `MagicLinkService` for passwordless authentication logic
60+
- Better separation of concerns between authentication methods
61+
- Cleaner dependency injection in main.go
62+
63+
- **Configuration System**
64+
- Auto-detection of available authentication methods
65+
- New `ACKIFY_AUTH_OAUTH_ENABLED` flag (optional, auto-detected)
66+
- New `ACKIFY_AUTH_MAGICLINK_ENABLED` flag (optional, auto-detected)
67+
- MagicLink enabled automatically if `ACKIFY_MAIL_HOST` is configured
68+
- OAuth enabled automatically if OAuth credentials are present
69+
- Enhanced email configuration with detailed SMTP options
70+
- Better validation and error messages for configuration issues
71+
72+
- **Session Management**
73+
- 30-day persistent sessions (increased from 7 days)
74+
- Encrypted refresh token storage with AES-256-GCM
75+
- New `oauth_sessions` table for refresh token persistence
76+
- Automatic cleanup of expired sessions (background worker)
77+
- Session tracking with IP address and User-Agent
78+
79+
- **User Interface**
80+
- New authentication choice page when multiple methods available
81+
- Auto-redirect behavior when single authentication method
82+
- Window variables for dynamic config (`ACKIFY_OAUTH_ENABLED`, `ACKIFY_MAGICLINK_ENABLED`)
83+
- Updated localization files (en, fr, es, de, it) with Magic Link strings
84+
85+
### Fixed
86+
87+
- Improved robustness of document metadata extraction
88+
- Better error handling in authentication flows
89+
- More descriptive error messages for configuration issues
90+
- Edge case handling in title extraction
91+
92+
### Technical Details
93+
94+
**New Files:**
95+
- `backend/internal/application/services/magic_link_service.go` - MagicLink service
96+
- `backend/internal/domain/models/magic_link.go` - MagicLink domain model
97+
- `backend/internal/infrastructure/auth/oauth_provider.go` - OAuth provider refactored
98+
- `backend/internal/infrastructure/auth/session_service.go` - Session management
99+
- `backend/internal/infrastructure/auth/session_worker_test.go` - Session cleanup tests
100+
- `backend/internal/infrastructure/database/magic_link_repository.go` - MagicLink repository
101+
- `backend/internal/infrastructure/workers/magic_link_cleanup.go` - Cleanup worker
102+
- `backend/internal/presentation/api/auth/magic_link_handler.go` - MagicLink endpoints
103+
- `backend/templates/magic_link.html.tmpl` - HTML email template
104+
- `backend/templates/magic_link.txt.tmpl` - Text email template
105+
- `backend/migrations/0012_magic_link_authentication.{up,down}.sql`
106+
- `webapp/src/pages/AuthChoicePage.vue` - Authentication method selection
107+
- `webapp/cypress/` - Complete E2E test suite
108+
- `.github/workflows/e2e-tests.yml` - E2E CI workflow
109+
- `install/README.md` - Installation documentation
110+
111+
**Modified Files:**
112+
- `backend/internal/infrastructure/config/config.go` - Enhanced configuration
113+
- `backend/internal/infrastructure/auth/oauth.go` - Refactored to use OAuthProvider
114+
- `backend/internal/presentation/api/router.go` - New Magic Link endpoints
115+
- `backend/pkg/web/server.go` - Multi-auth method support
116+
- `backend/pkg/web/static.go` - New window variables injection
117+
- `webapp/src/router/index.ts` - Auth choice route
118+
- `README.md`, `README_FR.md` - Updated with Magic Link documentation
119+
- `.env.example` - Comprehensive email and auth configuration
120+
121+
### Migration Guide
122+
123+
**For users upgrading from v1.2.0 to v1.2.1:**
124+
125+
1. **No Breaking Changes**: v1.2.1 is 100% backward compatible
126+
2. **Optional MagicLink**: Add email configuration to enable passwordless auth
127+
3. **Migrations**: Applied automatically at startup
128+
4. **Environment Variables**: Review new optional variables in `.env.example`
129+
130+
**To enable Magic Link authentication:**
131+
```bash
132+
# Add SMTP configuration
133+
ACKIFY_MAIL_HOST="smtp.example.com"
134+
ACKIFY_MAIL_PORT=587
135+
ACKIFY_MAIL_USERNAME="user"
136+
ACKIFY_MAIL_PASSWORD="pass"
137+
ACKIFY_MAIL_FROM="noreply@example.com"
138+
139+
# Optional: explicitly control auth methods
140+
ACKIFY_AUTH_OAUTH_ENABLED=true
141+
ACKIFY_AUTH_MAGICLINK_ENABLED=true
142+
```
143+
8144
## [1.2.0] - 2025-10-27
9145

10146
### 🎉 Major Release: API-First Vue Migration with Enhanced Security
@@ -283,6 +419,7 @@ For users upgrading from v1.1.x to v1.2.0:
283419
- NULL UserName handling in database operations
284420
- Proper string conversion for UserName field
285421

422+
[1.2.1]: https://github.com/btouchard/ackify-ce/compare/v1.2.0...v1.2.1
286423
[1.2.0]: https://github.com/btouchard/ackify-ce/compare/v1.1.3...v1.2.0
287424
[1.1.3]: https://github.com/btouchard/ackify-ce/compare/v1.1.2...v1.1.3
288425
[1.1.2]: https://github.com/btouchard/ackify-ce/compare/v1.1.1...v1.1.2

‎install/.env.example‎

Lines changed: 119 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,137 @@
1+
# ==========================================
2+
# Ackify Community Edition Configuration
3+
# ==========================================
4+
5+
# ==========================================
16
# Application Configuration
7+
# ==========================================
28
APP_BASE_URL=https://your-domain.com
39
APP_ORGANISATION="Your Organization Name"
410

11+
# ==========================================
512
# Database Configuration
13+
# ==========================================
614
POSTGRES_USER=ackifyr
715
POSTGRES_PASSWORD=your_secure_password
816
POSTGRES_DB=ackify
917

10-
# OAuth2 Configuration - Popular providers
11-
OAUTH_PROVIDER=google
12-
OAUTH_CLIENT_ID=your_oauth_client_id
13-
OAUTH_CLIENT_SECRET=your_oauth_client_secret
14-
OAUTH_ALLOWED_DOMAIN=@your-organization.com
15-
16-
# Security Configuration (generate with commands below)
18+
# ==========================================
19+
# Security Configuration (Auto-generated)
20+
# ==========================================
21+
# Generate with: openssl rand -base64 32
1722
OAUTH_COOKIE_SECRET=your_base64_encoded_secret_key
23+
24+
# Generate with: openssl rand 64 | base64 -w 0
1825
ED25519_PRIVATE_KEY_B64=your_base64_encoded_ed25519_private_key
1926

27+
# ==========================================
2028
# Server Configuration
29+
# ==========================================
2130
LISTEN_ADDR=:8080
2231

23-
# ========================================
32+
# ==========================================
33+
# OAuth2 Authentication Configuration
34+
# ==========================================
35+
# At least ONE authentication method (OAuth or MagicLink) must be enabled
36+
37+
# Provider: google, github, gitlab, or leave empty for custom
38+
OAUTH_PROVIDER=google
39+
40+
# OAuth Client Credentials
41+
OAUTH_CLIENT_ID=your_oauth_client_id
42+
OAUTH_CLIENT_SECRET=your_oauth_client_secret
43+
44+
# Optional: Restrict to specific email domain (e.g., @company.com)
45+
# OAUTH_ALLOWED_DOMAIN=@your-organization.com
46+
47+
# Optional: Auto-login if OAuth session exists (default: false)
48+
# OAUTH_AUTO_LOGIN=true
49+
50+
# Optional: Custom OAuth provider configuration (only if OAUTH_PROVIDER is empty)
51+
# OAUTH_AUTH_URL=https://your-provider.com/oauth/authorize
52+
# OAUTH_TOKEN_URL=https://your-provider.com/oauth/token
53+
# OAUTH_USERINFO_URL=https://your-provider.com/api/user
54+
# OAUTH_SCOPES=openid,email,profile
55+
56+
# Optional: Self-hosted GitLab URL (only if OAUTH_PROVIDER=gitlab)
57+
# OAUTH_GITLAB_URL=https://gitlab.your-company.com
58+
59+
# Optional: Custom logout URL
60+
# OAUTH_LOGOUT_URL=https://your-provider.com/logout
61+
62+
# Optional: Force enable/disable OAuth (auto-detected by default)
63+
# AUTH_OAUTH_ENABLED=true
64+
65+
# ==========================================
66+
# SMTP Configuration (Email Service)
67+
# ==========================================
68+
# SMTP is used for:
69+
# - Sending signature reminders to expected signers
70+
# - MagicLink authentication (passwordless email login)
71+
72+
# SMTP Server Configuration
73+
# MAIL_HOST=smtp.gmail.com
74+
# MAIL_PORT=587
75+
# MAIL_USERNAME=your-smtp-username
76+
# MAIL_PASSWORD=your-smtp-password
77+
78+
# Email Sender Configuration
79+
# MAIL_FROM=noreply@your-domain.com
80+
# MAIL_FROM_NAME=Your Organization Name
81+
82+
# SMTP Security Settings
83+
# MAIL_TLS=true
84+
# MAIL_STARTTLS=true
85+
# MAIL_TIMEOUT=10s
86+
87+
# Email Template Configuration
88+
# MAIL_TEMPLATE_DIR=templates/emails
89+
# MAIL_DEFAULT_LOCALE=en
90+
# MAIL_SUBJECT_PREFIX=[Ackify]
91+
92+
# ==========================================
93+
# MagicLink Authentication Configuration
94+
# ==========================================
95+
# MagicLink provides passwordless authentication via email
96+
# Auto-enabled when MAIL_HOST is configured
97+
98+
# Optional: Force disable MagicLink even if SMTP is configured
99+
# AUTH_MAGICLINK_ENABLED=false
100+
101+
# ==========================================
102+
# Admin Configuration
103+
# ==========================================
104+
# Comma-separated list of admin email addresses
105+
# Admins have access to document management and reminder features
106+
# ADMIN_EMAILS=admin@your-domain.com,admin2@your-domain.com
107+
108+
# ==========================================
24109
# CONFIGURATION INSTRUCTIONS
25-
# ========================================
110+
# ==========================================
26111

27-
# 1. Generate secure secrets:
112+
# 1. Run the interactive installation script:
113+
# bash <(curl -fsSL https://raw.githubusercontent.com/btouchard/ackify-ce/main/install/install.sh)
114+
115+
# 2. Or manually generate secure secrets:
28116
# OAUTH_COOKIE_SECRET=$(openssl rand -base64 32)
29-
# ED25519_PRIVATE_KEY_B64=$(openssl genpkey -algorithm Ed25519 | base64 -w 0)
30-
31-
# 2. OAuth2 Provider Configuration:
32-
# GOOGLE: OAUTH_PROVIDER=google
33-
# GITHUB: OAUTH_PROVIDER=github
34-
# GITLAB: OAUTH_PROVIDER=gitlab
35-
# CUSTOM: Leave OAUTH_PROVIDER empty and set:
36-
# OAUTH_AUTH_URL=https://your-provider.com/oauth/authorize
37-
# OAUTH_TOKEN_URL=https://your-provider.com/oauth/token
38-
# OAUTH_USERINFO_URL=https://your-provider.com/api/user
39-
# OAUTH_SCOPES=openid,email
40-
41-
# 3. For GitLab self-hosted:
42-
# OAUTH_GITLAB_URL=https://gitlab.your-company.com
43-
44-
# 4. Domain restriction (optional):
45-
# OAUTH_ALLOWED_DOMAIN=@company.com
117+
# ED25519_PRIVATE_KEY_B64=$(openssl rand 64 | base64 -w 0)
118+
119+
# 3. OAuth2 Provider Setup:
120+
# GOOGLE: Create OAuth credentials at https://console.cloud.google.com/
121+
# GITHUB: Create OAuth app at https://github.com/settings/developers
122+
# GITLAB: Create OAuth app at https://gitlab.com/-/profile/applications
123+
# CUSTOM: Use your own OAuth provider with custom URLs
124+
125+
# 4. SMTP Setup (for email reminders and MagicLink):
126+
# GMAIL: Use App Password from https://myaccount.google.com/apppasswords
127+
# SMTP2GO: Get credentials from https://www.smtp2go.com/
128+
# SendGrid: Use API key from https://app.sendgrid.com/settings/api_keys
129+
# Mailgun: Get credentials from https://app.mailgun.com/
130+
131+
# 5. Authentication Methods:
132+
# - OAuth: Requires OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET
133+
# - MagicLink: Requires MAIL_HOST configuration
134+
# - At least ONE method must be enabled
135+
136+
# 6. Start Ackify:
137+
# docker compose up -d

0 commit comments

Comments
 (0)