Skip to content

Commit 475ec58

Browse files
LlewellynvdmLlewellynvdm
committed
First public version
0 parents  commit 475ec58

File tree

202 files changed

+49274
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

202 files changed

+49274
-0
lines changed

‎.editorconfig‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# EditorConfig is awesome: https://EditorConfig.org
2+
3+
# top-most EditorConfig file
4+
root = true
5+
6+
[*]
7+
indent_style = tab
8+
indent_size = 4
9+
end_of_line = lf
10+
charset = utf-8
11+
trim_trailing_whitespace = true
12+
insert_final_newline = true

‎.github/workflows/joomengine.yml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
name: JoomEngine – Automated Build & Version Tracking
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
8+
schedule:
9+
# Runs once a day at 02:30 UTC
10+
- cron: "30 2 * * *"
11+
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: write
16+
packages: write
17+
18+
jobs:
19+
build-and-publish:
20+
name: Run joomengine.sh and track changes
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
# --------------------------------------------------
25+
# CHECKOUT
26+
# --------------------------------------------------
27+
- name: Checkout repository
28+
uses: actions/checkout@v4
29+
with:
30+
fetch-depth: 0
31+
32+
# --------------------------------------------------
33+
# TOOLING
34+
# --------------------------------------------------
35+
- name: Install required tooling
36+
run: |
37+
sudo apt-get update
38+
sudo apt-get install -y \
39+
jq \
40+
xmlstarlet \
41+
gawk \
42+
curl
43+
44+
# --------------------------------------------------
45+
# DOCKER AUTH (CI-ONLY)
46+
# --------------------------------------------------
47+
- name: Authenticate with Docker registry
48+
uses: docker/login-action@v3
49+
with:
50+
username: ${{ secrets.DOCKERHUB_USERNAME }}
51+
password: ${{ secrets.DOCKERHUB_TOKEN }}
52+
53+
# --------------------------------------------------
54+
# RUN SCRIPT
55+
# --------------------------------------------------
56+
- name: Run joomengine.sh
57+
run: |
58+
chmod +x ./joomengine.sh
59+
./joomengine.sh
60+
61+
# --------------------------------------------------
62+
# DETECT CHANGES
63+
# --------------------------------------------------
64+
- name: Detect repository changes
65+
id: git-status
66+
run: |
67+
if [[ -n "$(git status --porcelain)" ]]; then
68+
echo "changed=yes" >> "$GITHUB_OUTPUT"
69+
else
70+
echo "changed=no" >> "$GITHUB_OUTPUT"
71+
fi
72+
73+
# --------------------------------------------------
74+
# COMMIT BACK (ONLY IF NEEDED)
75+
# --------------------------------------------------
76+
- name: Commit and push changes
77+
if: steps.git-status.outputs.changed == 'yes'
78+
run: |
79+
DATE="$(date -u +'%Y-%m-%d')"
80+
81+
git config user.name "github-actions[bot]"
82+
git config user.email "github-actions[bot]@users.noreply.github.com"
83+
84+
git add -A
85+
git commit -m "chore: automated version update (${DATE})"
86+
git push
87+
88+
# --------------------------------------------------
89+
# NO-OP LOG (FOR VISIBILITY)
90+
# --------------------------------------------------
91+
- name: No changes detected
92+
if: steps.git-status.outputs.changed == 'no'
93+
run: |
94+
echo "ℹ️ No repository changes detected — nothing to commit."
95+

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.idea
2+
.jq-template.awk
3+
.log

‎DOCKER.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Joomla Component Builder – Official Docker Images
2+
3+
These are the **official Docker images for Joomla Component Builder (JCB)**.
4+
5+
Each image provides a **ready-to-use Joomla environment** with **Joomla Component Builder automatically installed** and optionally configurable via environment variables and CLI commands.
6+
7+
No manual installation. No guessing. Just run the container.
8+
9+
---
10+
11+
## 🚀 What You Get
12+
13+
- ✅ Joomla (official base image)
14+
- ✅ Joomla Component Builder (JCB) preloaded in the image
15+
- ✅ Automatic Joomla + JCB installation on first run
16+
- ✅ Safe one-time install (idempotent)
17+
- ✅ Deterministic, fail-fast container startup (`set -euo pipefail`)
18+
- ✅ Optional extension installation via URL or path
19+
- ✅ Optional Joomla CLI automation
20+
- ✅ SMTP configuration support
21+
- ✅ Runs as `www-data` (no root runtime)
22+
23+
These images are ideal for:
24+
25+
- Local JCB development
26+
- CI/CD pipelines
27+
- Automated component compilation
28+
- Reproducible Joomla build environments
29+
30+
---
31+
32+
## 📦 Available Images
33+
34+
All images are published under:
35+
```
36+
octoleo/joomengine
37+
```
38+
39+
Examples:
40+
```bash
41+
docker pull octoleo/joomengine:latest
42+
docker pull octoleo/joomengine:6.5.7
43+
docker pull octoleo/joomengine:6.5.7-php8.2-apache
44+
```
45+
46+
> `latest` always points to the **highest stable JCB release**, Apache variant, using the highest supported PHP version.
47+
48+
---
49+
50+
## 🧩 How It Works (Runtime Behavior)
51+
52+
When the container starts:
53+
54+
1. The **custom Joomla entrypoint** runs with strict error handling
55+
2. If Joomla is not installed and all required variables are present:
56+
* Joomla is **automatically installed**
57+
* Database is created/verified
58+
* Admin account is configured
59+
3. Once Joomla is configured (`configuration.php` exists):
60+
* Optional extensions are installed from URLs or paths
61+
* **Joomla Component Builder is installed automatically**
62+
* SMTP configuration is applied (if provided)
63+
* Optional Joomla CLI commands are executed
64+
4. The container continues running as `www-data`
65+
66+
This guarantees:
67+
68+
* ✓ Fails fast on misconfiguration
69+
* ✓ No silent fallbacks
70+
* ✓ No race conditions
71+
* ✓ No repeated installs
72+
* ✓ No root-owned Joomla files
73+
* ✓ Safe for repeated container restarts
74+
75+
---
76+
77+
## ⚙️ Environment Contract
78+
79+
This image is configured entirely via environment variables. All variables are optional unless stated otherwise.
80+
81+
The entrypoint runs in **strict mode** (`set -euo pipefail`). Missing or invalid critical values will cause the container to exit early and loudly.
82+
83+
### Required (Directly or Indirectly)
84+
85+
**Database Connection** - at least one of:
86+
- `JOOMLA_DB_HOST` - Database hostname (optionally `host:port`)
87+
- `MYSQL_PORT_3306_TCP` - Legacy Docker link support
88+
89+
**Database Password** - at least one of:
90+
- `JOOMLA_DB_PASSWORD` - Direct password
91+
- `JOOMLA_DB_PASSWORD_FILE` - Path to password file (e.g., Docker secrets)
92+
- `MYSQL_ENV_MYSQL_ROOT_PASSWORD` - Used when `JOOMLA_DB_USER=root`
93+
- `JOOMLA_DB_PASSWORD_ALLOW_EMPTY=yes` - Explicitly allow empty password
94+
95+
### Core Configuration Defaults
96+
97+
| Variable | Default |
98+
|----------|---------|
99+
| `JOOMLA_DB_USER` | `joomengine` |
100+
| `JOOMLA_DB_NAME` | `joomengine` |
101+
| `JOOMLA_DB_TYPE` | `mysqli` |
102+
| `JOOMLA_DB_PREFIX` | `joom_` |
103+
| `JOOMLA_SITE_NAME` | `Joomla Component Builder - JoomEngine` |
104+
| `JOOMLA_ADMIN_USER` | `JoomEngine Hero` |
105+
| `JOOMLA_ADMIN_USERNAME` | `joomengine` |
106+
| `JOOMLA_ADMIN_PASSWORD` | `joomengine@secure` |
107+
| `JOOMLA_ADMIN_EMAIL` | `joomengine@example.com` |
108+
109+
### Auto-Deploy Requirements
110+
111+
Automatic Joomla installation is performed **only if all** of the following are true:
112+
113+
- Joomla is not yet installed
114+
- The `installation/` directory exists
115+
- All admin variables are present and valid
116+
- Validation passes:
117+
- `JOOMLA_SITE_NAME` > 2 characters
118+
- `JOOMLA_ADMIN_USER` > 2 characters
119+
- `JOOMLA_ADMIN_USERNAME` alphabetical only
120+
- `JOOMLA_ADMIN_PASSWORD` > 12 characters
121+
- `JOOMLA_ADMIN_EMAIL` valid email format
122+
123+
If any condition fails, the container starts normally without auto-install.
124+
125+
### Optional Extension Installation
126+
127+
Multiple values must be **semicolon-separated** (`;`):
128+
129+
- `JOOMLA_EXTENSIONS_URLS` - URLs to install after Joomla setup
130+
- `JOOMLA_EXTENSIONS_PATHS` - Local paths to install after Joomla setup
131+
132+
⚠️ **URL validation is intentionally strict** (HTTPS/HTTP only, no IPs, no ports in domain).
133+
134+
### Joomla CLI Automation
135+
136+
- `JOOMLA_CLI_COMMANDS` - Semicolon-separated Joomla CLI commands
137+
138+
Each command is passed as-is to `cli/joomla.php`. **Shell tokenization is not performed.**
139+
140+
#### Example
141+
```yaml
142+
environment:
143+
JOOMLA_CLI_COMMANDS: "cache:clean;extension:list --type=component"
144+
```
145+
146+
What happens:
147+
148+
* Commands run **as `www-data`**
149+
* Executed only after Joomla and JCB are ready
150+
* Failures stop the container (safe by default)
151+
152+
### SMTP Configuration (Optional)
153+
154+
- `JOOMLA_SMTP_HOST` - Format: `hostname` or `hostname:port`
155+
156+
⚠️ **IPv4 only** - IPv6 addresses (e.g., `[::1]:587`) are not supported.
157+
158+
### Execution Guarantees
159+
160+
✓ Fails fast on misconfiguration
161+
✓ No silent fallbacks
162+
✓ Deterministic startup behavior
163+
✓ Safe for repeated container restarts
164+
✓ Compatible with Apache and PHP-FPM variants
165+
166+
---
167+
168+
## 🐳 Example `docker-compose.yml`
169+
170+
### Minimal Setup
171+
```yaml
172+
services:
173+
joomla:
174+
image: octoleo/joomengine:latest
175+
ports:
176+
- "8080:80"
177+
environment:
178+
JOOMLA_DB_HOST: mariadb:3306
179+
JOOMLA_DB_USER: joomengine
180+
JOOMLA_DB_NAME: joomengine
181+
JOOMLA_DB_PASSWORD: secure_password12345
182+
depends_on:
183+
- mariadb
184+
volumes:
185+
- joomla_data:/var/www/html
186+
187+
mariadb:
188+
image: mariadb:latest
189+
environment:
190+
MARIADB_USER: joomengine
191+
MARIADB_DATABASE: joomengine
192+
MARIADB_PASSWORD: secure_password12345
193+
MARIADB_ROOT_PASSWORD: your_root_secure_password12345
194+
volumes:
195+
- mariadb_data:/var/lib/mysql
196+
197+
volumes:
198+
joomla_data:
199+
mariadb_data:
200+
```
201+
202+
### With JCB CLI Automation
203+
```yaml
204+
services:
205+
joomla:
206+
image: octoleo/joomengine:latest
207+
ports:
208+
- "8080:80"
209+
environment:
210+
JOOMLA_DB_HOST: mariadb:3306
211+
JOOMLA_DB_USER: joomengine
212+
JOOMLA_DB_NAME: joomengine
213+
JOOMLA_DB_PASSWORD: secure_password12345
214+
JOOMLA_CLI_COMMANDS: "componentbuilder:pull:joomla_component --items=d7e30702-ec49-45ac-8897-0389d61d6da0"
215+
depends_on:
216+
- mariadb
217+
volumes:
218+
- joomla_data:/var/www/html
219+
220+
mariadb:
221+
image: mariadb:latest
222+
environment:
223+
MARIADB_USER: joomengine
224+
MARIADB_DATABASE: joomengine
225+
MARIADB_PASSWORD: secure_password12345
226+
MARIADB_ROOT_PASSWORD: your_root_secure_password12345
227+
volumes:
228+
- mariadb_data:/var/lib/mysql
229+
230+
volumes:
231+
joomla_data:
232+
mariadb_data:
233+
```
234+
235+
Open your browser at:
236+
```
237+
http://localhost:8080
238+
```
239+
240+
**Admin credentials:**
241+
- Username: `joomengine`
242+
- Password: `joomengine@secure`
243+
244+
---
245+
246+
## 🔐 Security & Permissions
247+
248+
* Joomla and JCB always run as `www-data`
249+
* Root is used **only** during bootstrap if required
250+
* File ownership is corrected automatically
251+
* Safe for persistent volumes
252+
* Strict mode prevents silent misconfigurations
253+
254+
---
255+
256+
## 🧾 License
257+
258+
Copyright (C) 2021–2026
259+
Llewellyn van der Merwe
260+
261+
Licensed under the **GNU General Public License v2 (GPLv2)**
262+
263+
See `LICENSE` for details.

0 commit comments

Comments
 (0)