Skip to content

Commit 27d5656

Browse files
freephilefreephile
committed
doc getmeza.sh
Verbose version Addresses Issue #172
1 parent 45ad0b8 commit 27d5656

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎src/scripts/getmeza.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# getmeza.sh - Meza Bootstrap Installation Script
2+
3+
## Overview
4+
5+
The `getmeza.sh` script is the primary bootstrap installer for the Meza MediaWiki deployment platform. It performs initial system setup, installs dependencies, clones the Meza repository, and prepares the system for MediaWiki deployment automation.
6+
7+
## Purpose
8+
9+
This script serves as the entry point for installing Meza on a fresh Linux system. It handles:
10+
11+
- Operating system detection and compatibility checking
12+
- Installation of required system packages and repositories
13+
- Git repository cloning and initial configuration
14+
- User account creation and permissions setup
15+
- Ansible environment preparation
16+
17+
## Usage
18+
19+
```bash
20+
# Standard installation (requires root privileges)
21+
sudo bash getmeza.sh
22+
23+
# Skip internet connectivity check (useful for offline/restricted environments)
24+
sudo bash getmeza.sh --skip-conn-check
25+
```
26+
27+
### Requirements
28+
29+
- **Root privileges**: Must be run as root or with sudo
30+
- **Internet connection**: Required for package installation and git cloning (unless `--skip-conn-check` is used)
31+
- **Supported OS**: Red Hat Enterprise Linux, or Rocky Linux
32+
33+
## Command Line Options
34+
35+
| Option | Description |
36+
|--------|-------------|
37+
| `--skip-conn-check` | Skip internet connectivity verification (use for Continuous Integration like GitHub Actions) |
38+
39+
## Environment Variables
40+
41+
The script respects the following environment variables for customization:
42+
43+
| Variable | Default | Description |
44+
|----------|---------|-------------|
45+
| `MEZA_REPOSITORY_URL` | `https://github.com/nasa/meza.git` | Git repository URL to clone from |
46+
| `MEZA_BRANCH_NAME` | `main` | Git branch to checkout |
47+
48+
### Example with Custom Repository
49+
50+
```bash
51+
export MEZA_REPOSITORY_URL='https://github.com/freephile/meza.git'
52+
export MEZA_BRANCH_NAME='REL1_39'
53+
sudo bash getmeza.sh
54+
```
55+
56+
## What the Script Does
57+
58+
### 1. Root Permission Check
59+
- Verifies the script is running as root
60+
- Exits with error message if not running with sufficient privileges
61+
62+
### 2. Internet Connectivity Validation
63+
- Tests connection to `cdn.redhat.com` with up to 100 retry attempts
64+
- Provides detailed feedback on connection status
65+
- Can be skipped with `--skip-conn-check` flag
66+
67+
### 3. Operating System Detection
68+
- Identifies Red Hat variants (RHEL, Rocky Linux)
69+
- Determines version numbers for package management decisions
70+
- Exits if unsupported OS is detected
71+
72+
### 4. Directory Structure Creation
73+
```
74+
/opt/conf-meza/ # Configuration directory (755 permissions)
75+
/opt/conf-meza/secret/ # Secret configuration (775 permissions)
76+
/opt/data-meza/ # Data directory for locks and runtime files
77+
/opt/.deploy-meza/ # Deployment configuration (755 permissions)
78+
```
79+
80+
### 5. Repository Installation (EPEL)
81+
- **Rocky Linux**: Enables PowerTools repository and installs EPEL
82+
- **RHEL**: Enables CodeReady Builder and Ansible repositories based on version
83+
84+
### 6. Package Installation
85+
Installs core dependencies based on OS:
86+
- **Git**: Version control for Meza repository
87+
- **Ansible**: Automation framework for deployments
88+
- **Python**: Runtime environment and SELinux bindings
89+
- **libselinux-python/python3-libselinux**: SELinux integration
90+
91+
### 7. Repository Cloning
92+
- Clones Meza repository to `/opt/meza`
93+
- Uses configurable repository URL and branch
94+
- Sets appropriate file permissions (readable by all users, executable directories)
95+
96+
### 8. System Integration
97+
- Creates symbolic link: `/usr/bin/meza` → `/opt/meza/src/scripts/meza.py`
98+
- Generates a shell version of meza's configuration variables at `/opt/.deploy-meza/config.sh`
99+
100+
### 9. User Account Management
101+
- Creates or updates `meza-ansible` user account
102+
- Migrates home directory from `/home/meza-ansible` to `/opt/conf-meza/users/meza-ansible`
103+
- Sets up proper ownership and permissions for Meza directories
104+
105+
### 10. System Security Configuration
106+
- Disables TTY requirement for sudo operations
107+
- Removes visible password requirement for sudo
108+
- Configures permissions for ansible operations
109+
110+
### 11. Ansible Environment Setup
111+
- Installs Ansible in the meza-ansible user's Python environment
112+
- Installs required Ansible collections from `requirements.yml`
113+
114+
## File Locations
115+
116+
| Path | Purpose |
117+
|------|---------|
118+
| `/opt/meza/` | Main Meza installation directory |
119+
| `/opt/conf-meza/` | Configuration files and secrets |
120+
| `/opt/data-meza/` | Runtime data and lock files |
121+
| `/opt/.deploy-meza/config.sh` | Basic deployment configuration |
122+
| `/usr/bin/meza` | System-wide meza command symlink |
123+
124+
## Supported Operating Systems
125+
126+
### Red Hat Enterprise Linux (RHEL)
127+
- **Version 7.x**: Uses YUM package manager
128+
- **Version 8.x**: Uses DNF, enables specific repositories and PHP modules
129+
130+
### CentOS
131+
- Uses YUM package manager
132+
- Installs EPEL repository automatically
133+
134+
### Rocky Linux
135+
- Uses DNF package manager
136+
- Enables PowerTools repository
137+
- Configures PHP and Python exclusions
138+
- Resets and enables PHP 7.4 module
139+
140+
## Security Considerations
141+
142+
- **Root Execution**: Script requires root privileges for system-wide changes
143+
- **Network Access**: Downloads packages and repositories from internet
144+
- **User Creation**: Creates system user `meza-ansible` with sudo access
145+
- **Sudo Configuration**: Modifies sudoers file to disable TTY requirements
146+
- **File Permissions**: Sets specific permissions on configuration directories
147+
148+
## Error Handling
149+
150+
The script includes comprehensive error handling:
151+
152+
- **Exit Code 1**: Not running as root
153+
- **Exit Code 187**: Unsupported RedHat version or unknown distro
154+
- **Exit Code 188**: Unsupported RedHat version during package installation
155+
- **Exit Code 189**: Cannot determine OS distro/version during package installation
156+
157+
## Next Steps
158+
159+
After successful completion, the script displays:
160+
161+
```
162+
meza command installed. Use it:
163+
sudo meza deploy monolith -vvv
164+
```
165+
166+
This indicates the system is ready for MediaWiki deployment using the Meza automation platform.
167+
168+
## Development Notes
169+
170+
- **TODO**: Refactor and document script better (see [Issue #172](https://github.com/freephile/meza/issues/172#issuecomment-3141998590))
171+
- **Umask**: Sets umask 002 to ensure proper permissions for git operations
172+
- **Compatibility**: Designed for restrictive systems where permission management is critical
173+
174+
## Related Documentation
175+
176+
- [Meza Installation Guide](../../manual/meza-cmd/install.md)
177+
- [Meza Setup Documentation](../../manual/meza-cmd/setup.md)
178+
- [Deployment Guide](../../manual/meza-cmd/deploy.md)

0 commit comments

Comments
 (0)