feat: Add professional hierarchical documentation
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
- Created comprehensive README.md with Mermaid diagrams, badges, and TOC - Added docs/ directory with 7 sections and 14 markdown files - Included architecture diagrams, flowcharts, and sequence diagrams - All documentation is fully interlinked with cross-references - Added ISO storage location on Proxmox development server - Included troubleshooting guide and evaluation management docs - All config files (Packer, Terraform, Ansible, Forgejo) documented - Added icons and visual elements throughout documentation
This commit is contained in:
root
parent
faf04d69f8
commit
e4f03427b7
24 changed files with 3844 additions and 2 deletions
224
docs/02-prerequisites/secrets.md
Normal file
224
docs/02-prerequisites/secrets.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# 🔐 Secret Management
|
||||
|
||||
[](https://forgejo.org/docs/user/actions/secrets/)
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes how to configure required secrets for the CI/CD pipeline. All secrets should be stored securely in Forgejo and never committed to the repository.
|
||||
|
||||
---
|
||||
|
||||
## Required Secrets
|
||||
|
||||
| Secret Name | Description | Used By | Required |
|
||||
|-------------|-------------|---------|----------|
|
||||
| `PFX_PASS` | Code signing certificate password | osslsigncode | ✅ Yes |
|
||||
| `PM_TOKEN_ID` | Proxmox API token ID | OpenTofu | ✅ Yes |
|
||||
| `PM_TOKEN_SECRET` | Proxmox API token secret | OpenTofu | ✅ Yes |
|
||||
| `WIN_ADMIN_PASS` | Windows Administrator password | Ansible | ✅ Yes |
|
||||
|
||||
---
|
||||
|
||||
## Forgejo Configuration
|
||||
|
||||
### Accessing Secrets
|
||||
|
||||
1. Navigate to your Forgejo repository
|
||||
2. Go to **Settings** → **Secrets**
|
||||
3. Add each secret with the exact names listed below
|
||||
|
||||
### Required Secrets List
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph Forgejo["Forgejo Settings"]
|
||||
Settings["Settings"] --> Secrets["Secrets"]
|
||||
Secrets --> Add["Add Secret"]
|
||||
Add --> |"Enter Name & Value"| Created[Secret Created]
|
||||
end
|
||||
|
||||
subgraph CreatedSecrets["Configured Secrets"]
|
||||
PFX["🔐 PFX_PASS"]
|
||||
PM_ID["🔑 PM_TOKEN_ID"]
|
||||
PM_SEC["🔑 PM_TOKEN_SECRET"]
|
||||
WIN["🪟 WIN_ADMIN_PASS"]
|
||||
end
|
||||
|
||||
Created --> PFX
|
||||
Created --> PM_ID
|
||||
Created --> PM_SEC
|
||||
Created --> WIN
|
||||
|
||||
style Forgejo fill:#e1f5fe
|
||||
style CreatedSecrets fill:#e8f5e9
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proxmox API Token
|
||||
|
||||
### Create API Token
|
||||
|
||||
1. **SSH to Proxmox host:**
|
||||
```bash
|
||||
ssh root@la-vmh-07
|
||||
```
|
||||
|
||||
2. **Navigate to API Tokens:**
|
||||
- Go to **Datacenter** → **API Tokens**
|
||||
- Click **Add**
|
||||
|
||||
3. **Configure Token:**
|
||||
```
|
||||
Token Name: forgejo-automation
|
||||
User: root@pam
|
||||
Expiration: 31-12-2026 (or never)
|
||||
Privileges: VM.Admin (or Administrator)
|
||||
```
|
||||
|
||||
4. **Save Credentials:**
|
||||
```
|
||||
Token ID: root@pam!forgejo-automation
|
||||
Secret: <YOUR_SECRET_VALUE>
|
||||
```
|
||||
|
||||
### Set Environment Variables
|
||||
|
||||
```bash
|
||||
# In Forgejo workflow or local environment
|
||||
export PM_API_TOKEN_ID="root@pam!forgejo-automation"
|
||||
export PM_API_TOKEN_SECRET="<your-token-secret>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Signing Certificate
|
||||
|
||||
### Certificate Requirements
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Format** | PKCS#12 (.pfx or .p12) |
|
||||
| **Algorithm** | SHA-256 |
|
||||
| **Timestamp Server** | http://timestamp.digicert.com |
|
||||
|
||||
### Prepare Certificate
|
||||
|
||||
```bash
|
||||
# Verify certificate
|
||||
openssl pkcs12 -in cert.pfx -info -noout
|
||||
|
||||
# Extract for use (if needed)
|
||||
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
|
||||
openssl pkcs12 -in cert.pfx -nocerts -out key.pem
|
||||
```
|
||||
|
||||
### Set Password Secret
|
||||
|
||||
```bash
|
||||
# Set PFX_PASS secret in Forgejo
|
||||
export PFX_PASS="your-certificate-password"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Windows Administrator Password
|
||||
|
||||
### Requirements
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Account** | Administrator |
|
||||
| **Complexity** | Windows complexity requirements |
|
||||
| **Length** | Minimum 12 characters |
|
||||
|
||||
### Configuration in Autounattend.xml
|
||||
|
||||
The password is configured in [`packer/Autounattend.xml`](../../packer/Autounattend.xml):
|
||||
|
||||
```xml
|
||||
<UserAccounts>
|
||||
<AdministratorPassword>
|
||||
<Value>PackerPassword123!</Value>
|
||||
<PlainText>true</PlainText>
|
||||
</AdministratorPassword>
|
||||
</UserAccounts>
|
||||
```
|
||||
|
||||
### Ansible Integration
|
||||
|
||||
```yaml
|
||||
# ansible/pipeline.yml
|
||||
- name: Verify Installer
|
||||
hosts: windows_vm
|
||||
vars:
|
||||
ansible_user: Administrator
|
||||
ansible_password: "{{ lookup('env', 'WIN_ADMIN_PASS') }}"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph BestPractices["Security Guidelines"]
|
||||
direction TB
|
||||
NeverCommit["❌ Never commit secrets to git"]
|
||||
RotateKeys["🔄 Rotate keys regularly"]
|
||||
UseVault["🔐 Use Forgejo Secrets"]
|
||||
LimitScopes["📊 Limit token privileges"]
|
||||
AuditLogs["📝 Audit access logs"]
|
||||
end
|
||||
|
||||
NeverCommit --> RotateKeys
|
||||
RotateKeys --> UseVault
|
||||
UseVault --> LimitScopes
|
||||
LimitScopes --> AuditLogs
|
||||
|
||||
style BestPractices fill:#ffebee
|
||||
```
|
||||
|
||||
| Practice | Description |
|
||||
|----------|-------------|
|
||||
| **Never commit secrets** | Use .gitignore for .pfx, .env files |
|
||||
| **Rotate keys** | Rotate Proxmox tokens quarterly |
|
||||
| **Use Forgejo Secrets** | Store all secrets in Forgejo settings |
|
||||
| **Limit scopes** | Use minimum required privileges |
|
||||
| **Audit access** | Review Proxmox API access logs |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Mapping
|
||||
|
||||
| Secret | Env Var | Usage |
|
||||
|--------|---------|-------|
|
||||
| `PFX_PASS` | `PFX_PASS` | osslsigncode command |
|
||||
| `PM_TOKEN_ID` | `PM_API_TOKEN_ID` | OpenTofu provider |
|
||||
| `PM_TOKEN_SECRET` | `PM_API_TOKEN_SECRET` | OpenTofu provider |
|
||||
| `WIN_ADMIN_PASS` | `ANSIBLE_PASSWORD` | Ansible connection |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| Token invalid | Token expired | Create new token in Proxmox |
|
||||
| Permission denied | Insufficient privileges | Add VM.Admin to token |
|
||||
| Password rejected | Windows complexity | Use stronger password |
|
||||
| Certificate invalid | Wrong format | Convert to PKCS#12 |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
| Goal | Next Document |
|
||||
|------|---------------|
|
||||
| Configure ISOs | [ISO Requirements](isos.md) |
|
||||
| Build template | [Packer Configuration](../03-packer/configuration.md) |
|
||||
| View architecture | [Architecture Overview](../01-overview/architecture.md) |
|
||||
|
||||
---
|
||||
|
||||
[← Documentation Index](../index.md) | [→ ISO Requirements](isos.md) | [← Architecture](../01-overview/architecture.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue