Skip to content

Commit 016aacb

Browse files
freephilefreephile
committed
Add autodeployer doc
- improve doc for 'debug' - correct doc for 'config' - there's no such command, but we explain how config is managed in meza - move cleanup-backups script documentation to scripts directory Fixes Issue #211
1 parent 64c1e8e commit 016aacb

File tree

5 files changed

+245
-52
lines changed

5 files changed

+245
-52
lines changed

‎manual/meza-cmd/autodeploy.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# meza autodeploy
2+
3+
Perform automated deployment with change detection for continuous integration/deployment workflows.
4+
5+
## Usage
6+
7+
```bash
8+
meza autodeploy <environment> [deploy_type] [deploy_args] [ansible-options]
9+
```
10+
11+
## Arguments
12+
13+
| Argument | Description | Required | Default |
14+
|----------|-------------|----------|---------|
15+
| `environment` | Target environment name | Yes | - |
16+
| `deploy_type` | Type of deployment to perform | No | standard |
17+
| `deploy_args` | Additional deployment arguments | No | - |
18+
| `ansible-options` | Standard Ansible playbook options | No | - |
19+
20+
## Description
21+
22+
The `autodeploy` command is designed for automated deployment scenarios, particularly useful for:
23+
24+
- **Continuous Integration/Deployment (CI/CD)** pipelines
25+
- **Cron-based automated deployments** that check for changes
26+
- **Scheduled maintenance deployments** with change detection
27+
- **Remote deployment triggers** from external systems
28+
29+
This command differs from regular `deploy` in that it:
30+
- Includes built-in change detection mechanisms
31+
- Can be safely run repeatedly (only deploys when changes detected)
32+
- Optimized for unattended/automated execution
33+
- Includes additional logging for automation workflows
34+
35+
## Examples
36+
37+
### Basic Autodeploy
38+
```bash
39+
# Autodeploy to production environment
40+
sudo meza autodeploy production
41+
42+
# Autodeploy with specific deployment type
43+
sudo meza autodeploy production config-only
44+
```
45+
46+
### CI/CD Integration
47+
```bash
48+
# In CI/CD pipeline with verbose logging
49+
sudo meza autodeploy production standard --verbose >> /var/log/meza-autodeploy.log 2>&1
50+
51+
# With specific tags for faster deployment
52+
sudo meza autodeploy production quick --tags mediawiki,sync-configs
53+
```
54+
55+
### Cron Job Usage
56+
```bash
57+
# Example cron entry for nightly automates deployments
58+
# Check for changes and deploy if needed every night at 2 AM
59+
0 2 * * * /usr/local/bin/meza autodeploy production >> /var/log/meza-cron.log 2>&1
60+
```
61+
62+
## Deploy Types
63+
64+
| Type | Description | Use Case |
65+
|------|-------------|----------|
66+
| `standard` | Full deployment with all checks | Default automated deployment |
67+
| `config-only` | Configuration changes only | Quick config updates |
68+
| `quick` | Skip time-intensive verification | Fast deployments |
69+
| `maintenance` | Include maintenance tasks | Scheduled maintenance windows |
70+
71+
## Deployment Lock Behavior
72+
73+
- **Automatic lock management**: Creates deployment locks to prevent concurrent runs
74+
- **Lock detection**: Exits gracefully if another deployment is in progress
75+
- **Safe for automation**: Won't interfere with manual deployments
76+
77+
## Change Detection
78+
79+
The autodeploy command includes intelligent change detection:
80+
- **Git repository changes** in Meza core
81+
- **Configuration file modifications** in conf-meza
82+
- **Environment-specific changes** in secret and public configs
83+
84+
## Logging and Monitoring
85+
86+
All autodeploy operations include enhanced logging:
87+
- **Deployment logs**: Written to standard Meza log locations
88+
- **Change detection logs**: Details about what triggered the deployment
89+
- **Exit codes**: Proper return codes for automation integration
90+
91+
## Exit Codes
92+
93+
| Code | Meaning |
94+
|------|---------|
95+
| `0` | Success (deployment completed or no changes detected) |
96+
| `1` | Deployment failure or environment error |
97+
| `2` | Lock file conflict (another deployment in progress) |
98+
99+
## Security Considerations
100+
101+
- **Run as privileged user**: Requires sudo/root access
102+
- **Vault password access**: Must have access to environment vault passwords
103+
- **SSH key access**: Requires SSH keys for multi-server deployments
104+
105+
## Troubleshooting
106+
107+
### Common Issues
108+
109+
**Deployment locks stuck:**
110+
```bash
111+
# Check lock status
112+
sudo meza deploy-check production
113+
114+
# Remove stuck lock if needed
115+
sudo meza deploy-unlock production
116+
```
117+
118+
**Permission errors:**
119+
```bash
120+
# Ensure proper ownership of config files
121+
sudo chown -R meza-ansible:wheel /opt/conf-meza/
122+
```
123+
124+
**Change detection not working:**
125+
```bash
126+
# Manually verify git status
127+
cd /opt/meza && git status
128+
cd /opt/conf-meza && git status
129+
```
130+
131+
## See Also
132+
133+
- [`meza deploy`](deploy.md) - Manual deployment command
134+
- [`meza deploy-check`](deploy-check.md) - Check deployment status
135+
- [`meza deploy-lock`](deploy-lock.md) - Manual deployment locking
136+
- [`meza backup`](backup.md) - Create backups before deployment
137+
138+
## Integration Examples
139+
140+
### Jenkins Pipeline
141+
```groovy
142+
pipeline {
143+
agent any
144+
stages {
145+
stage('Deploy') {
146+
steps {
147+
sh 'sudo meza autodeploy production'
148+
}
149+
}
150+
}
151+
}
152+
```
153+
154+
### GitHub Actions
155+
```yaml
156+
- name: Autodeploy Meza
157+
run: sudo meza autodeploy production
158+
env:
159+
ANSIBLE_HOST_KEY_CHECKING: False
160+
```

‎manual/meza-cmd/config.md‎

Lines changed: 71 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,95 @@
1-
# Meza Command: `config`
1+
# Meza Configuration Management
22

3-
## Description
3+
## No `meza config` Command Available
44

5-
Get or set configuration values for Meza environments.
5+
There is no `meza config` command in the current implementation. Such a command would require:
66

7-
## Usage
7+
- A complex configuration management system
8+
- Direct YAML file manipulation capabilities
9+
- Environment-aware key/value storage
10+
- Integration with Meza's multi-layered configuration hierarchy
11+
12+
This level of complexity doesn't align with Meza's current architecture, which is designed around direct file editing and Ansible-based configuration management.
13+
14+
## Managing config in Meza
15+
16+
Here is how Meza provides configuration management (get/set/apply):
17+
18+
### View Configuration Values
19+
20+
Use the `meza debug` command to view any configuration variable:
821

922
```bash
10-
meza config <key> [value]
23+
# View a specific configuration value
24+
meza debug monolith mediawiki_version
25+
26+
# View database configuration
27+
Meza database configuration starts with the 'inventory' file
28+
29+
# View all wikis configured
30+
meza debug production list_of_wikis
31+
32+
# View backup settings
33+
meza debug monolith m_backup_retention_days
1134
```
1235

13-
## Examples
36+
Remember that it is fast and useful to just grep the two config hierarchies:
37+
`grep -r is_this_even_real /opt/conf-meza /opt/meza'
1438

15-
```bash
16-
# Get current value of a configuration key
17-
meza config database_host
39+
### Set Configuration Values
1840

19-
# Set a configuration value
20-
meza config database_host "db.example.com"
41+
Edit configuration files directly using your preferred editor:
2142

22-
# Get MediaWiki version setting
23-
meza config mediawiki_version
43+
```bash
44+
# Edit public (non-sensitive) configuration
45+
sudo vi /opt/conf-meza/public/monolith/public.yml
46+
47+
# Edit secret (sensitive) configuration
48+
sudo vi /opt/conf-meza/secret/monolith/secret.yml
2449

25-
# Set environment-specific setting
26-
meza config backup_retention_days 30
50+
# Edit global defaults (affects all environments)
51+
# This is only for changes to the project itself
52+
sudo vi /opt/meza/config/defaults.yml
2753
```
2854

29-
## Arguments
55+
### Apply Configuration Changes
56+
57+
Deploy the environment to apply configuration changes:
58+
59+
```bash
60+
# Apply all configuration changes
61+
meza deploy monolith
3062

31-
| Argument | Description | Required |
32-
|----------|-------------|----------|
33-
| `<key>` | Configuration key to get or set | ✓ |
34-
| `[value]` | Value to set (omit to get current value) | No |
63+
# Apply only configuration changes (faster, skips updates)
64+
meza deploy monolith --tags mediawiki --skip-tags latest,update.php
65+
```
3566

36-
## Behavior
67+
## Configuration File Hierarchy
3768

38-
- **With value**: Sets the configuration key to the specified value
39-
- **Without value**: Displays the current value of the configuration key (if it exists)
69+
Meza uses a layered configuration system where values are resolved in this order:
4070

41-
## Notes
71+
1. **Environment secrets**: `/opt/conf-meza/secret/<env>/secret.yml` (highest priority)
72+
2. **Environment public**: `/opt/conf-meza/public/<env>/public.yml`
73+
3. **OS-specific defaults**: `/opt/meza/config/RedHat.yml` or `/opt/meza/config/Debian.yml`
74+
4. **Global defaults**: `/opt/meza/config/defaults.yml` (lowest priority)
4275

43-
- Configuration changes may require redeployment to take effect
44-
- Some configuration keys are environment-specific
45-
- Critical settings should be verified before deployment
46-
- Use `meza deploy` to apply configuration changes
76+
## Common Configuration Examples
4777

48-
## Common Configuration Keys
78+
### MediaWiki Version
79+
```yaml
80+
# In /opt/conf-meza/public/production/public.yml
81+
mediawiki_version: "1.39.4"
82+
```
4983
50-
| Key | Description | Example |
51-
|-----|-------------|---------|
52-
| `database_host` | Database server hostname | `db.example.com` |
53-
| `mediawiki_version` | MediaWiki version to deploy | `1.39.4` |
54-
| `backup_retention_days` | Days to keep backups | `30` |
55-
| `php_version` | PHP version to use | `8.1` |
84+
### Backup Configuration
85+
```yaml
86+
# In /opt/conf-meza/public/production/public.yml
87+
m_backup_retention_days: 30
88+
m_backup_enable: true
89+
```
5690
5791
## See Also
5892
93+
- [`meza debug`](debug.md) - View configuration values and variables
5994
- [`meza deploy`](deploy.md) - Apply configuration changes
60-
- [`meza setup`](setup.md) - Environment setup
61-
- [`meza debug`](debug.md) - Debug configuration values
95+
- [`meza setup`](setup.md) - Environment setup and initial configuration

‎manual/meza-cmd/debug.md‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,12 @@ meza debug <environment> <variable_name>
1616
# Debug specific variables
1717
meza debug monolith m_wikis
1818
meza debug production m_install
19-
meza debug development m_mediawiki_version
19+
meza debug development mediawiki_version
2020

2121
# Debug environment paths
2222
meza debug monolith m_uploads_dir
2323
meza debug monolith m_conf_meza_public
2424

25-
# Debug database configuration
26-
meza debug production m_db_master_server
27-
meza debug production m_db_slave_servers
2825
```
2926

3027
## Arguments
@@ -38,24 +35,24 @@ meza debug production m_db_slave_servers
3835

3936
| Variable | Description |
4037
|----------|-------------|
41-
| `m_wikis` | List of configured wikis |
38+
| `list_of_wikis` | List of configured wikis |
4239
| `m_install` | Meza installation directory |
4340
| `m_uploads_dir` | Wiki uploads directory |
44-
| `m_mediawiki_version` | MediaWiki version |
41+
| `mediawiki_version` | MediaWiki version |
4542
| `m_conf_meza_public` | Public configuration directory |
4643
| `m_conf_meza_secret` | Secret configuration directory |
47-
| `m_db_master_server` | Database master server |
48-
| `m_db_slave_servers` | Database slave servers |
4944

5045
## Notes
5146

5247
- Uses Ansible's debug module to display variable values
5348
- Loads environment configuration through set-vars role
5449
- Useful for troubleshooting configuration issues
5550
- Can inspect any Ansible variable available in the environment
51+
- It is fast and useful to just grep the two config hierarchies:
52+
- `grep -r is_this_even_real /opt/conf-meza /opt/meza'
5653

5754
## See Also
5855

5956
- [`meza list-wikis`](list-wikis.md) - List wikis (uses debug internally)
6057
- [`meza deploy`](deploy.md) - Deploy environment
61-
- [`meza setup-env`](setup.md) - Environment setup
58+
- [`meza setup-env`](setup.md) - Environment setup

‎src/roles/logrotate/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -171,11 +171,13 @@ The logrotate configuration includes:
171171
172172
## 📚 Related Documentation
173173
174-
- [Logrotate Role Tasks](../tasks/main.yml)
175-
- [Logrotate Default Variables](../defaults/main.yml)
176-
- [Logrotate Templates](../templates/)
177-
- [Backup Cleanup Script](../templates/cleanup-backups.sh.j2)
174+
- [Logrotate Role Tasks](https://github.com/freephile/meza/blob/dev/src/roles/logrotate/tasks/main.yml)
175+
- [Logrotate Default Variables](https://github.com/freephile/meza/blob/dev/src/roles/logrotate/defaults/main.yml)
176+
- [Logrotate Templates](https://github.com/freephile/meza/blob/dev/src/roles/logrotate/templates/)
177+
- See the generated configuration for logrotate at `/etc/logrotate.d/meza-logs`
178+
- The [cleanup-backups.sh script](https://github.com/freephile/meza/blob/dev/src/scripts/cleanup-backups.sh) is output to the 'scripts' directory.
179+
- [Backup Cleanup Script Documentation](https://github.com/freephile/meza/blob/dev/src/scripts/cleanup-backups.md) (markdown) is side-by-side in the 'scripts' directory.
178180

179181
---
180182

181-
*This documentation is automatically maintained as part of the Meza logrotate role. Last updated: October 22, 2025*
183+
*This documentation is automatically maintained as part of the Meza logrotate role. Last updated: October 22, 2025*

‎manual/meza-cmd/cleanup-backups.md‎ renamed to ‎src/scripts/cleanup-backups.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,4 +178,4 @@ du -sh /opt/data-meza/backups/
178178
- [`meza backup`](backup.md) - Create database and file backups
179179
- [`meza deploy`](deploy.md) - Deploy environments with backup management
180180
- [Logrotate Role README](/opt/meza/src/roles/logrotate/README.md) - Comprehensive log management
181-
- [Meza Backup Strategy Documentation](/opt/meza/manual/) - Backup best practices
181+
- [Meza Backup Strategy Documentation](/opt/meza/manual/) - Backup best practices

0 commit comments

Comments
 (0)