Skip to content

Commit be25816

Browse files
akiletourakiletour
authored
📝 Rewrite README with full project documentation (#78)
2 parents 0fe2598 + 8882d24 commit be25816

File tree

1 file changed

+187
-24
lines changed

1 file changed

+187
-24
lines changed

‎README.md‎

Lines changed: 187 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,63 +3,226 @@
33
</p>
44

55
<p align="center">
6-
Octa is a Powerful WordPress theme based on Laravel, Bedrock and Sage
6+
<strong>Octa</strong> — A modern WordPress boilerplate built on Bedrock, Sage/Acorn 5, Vite, Tailwind CSS 4 and Alpine.js
77
</p>
88

9-
## Getting started
9+
<p align="center">
10+
<a href="https://github.com/inrage/octa/actions"><img src="https://github.com/inrage/octa/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
12+
</p>
1013

11-
### Local development
14+
---
1215

13-
1. Install Node dependencies:
16+
## Tech Stack
1417

15-
```bash
16-
pnpm install
18+
| Layer | Technology |
19+
|-------|-----------|
20+
| CMS | WordPress 6.9 (Composer-managed) |
21+
| PHP Framework | Acorn 5 (Laravel-style) |
22+
| Structure | Bedrock |
23+
| Templating | Blade |
24+
| Bundler | Vite 7 |
25+
| CSS | Tailwind CSS 4 |
26+
| JS | Alpine.js 3, TypeScript |
27+
| Docker | MariaDB 11.4, PHP-FPM 8.4, Nginx |
28+
| CI | GitHub Actions |
1729

18-
```
30+
## Requirements
1931

20-
2. Install Composer dependencies:
32+
- PHP >= 8.4
33+
- Node >= 24
34+
- Composer 2
35+
- pnpm
36+
- Docker (optional)
37+
38+
## Getting Started
39+
40+
### 1. Install dependencies
2141

2242
```bash
2343
composer install
44+
pnpm install
2445
```
2546

26-
3. Create a `.env.local` file:
47+
### 2. Configure environment
2748

2849
```bash
2950
cp .env .env.local
3051
```
3152

32-
## Configuration
53+
Edit `.env.local` with your database credentials and site URL:
3354

34-
```bash
35-
PROJECT_NAME='octa'
55+
```env
56+
PROJECT_NAME='my-project'
3657
3758
DB_HOST='database'
3859
DB_NAME='database_name'
3960
DB_USER='database_user'
4061
DB_PASSWORD='database_password'
41-
DB_ROOT_PASSWORD='root_password'
62+
63+
WP_ENV='development'
64+
WP_HOME='http://127.0.0.1:8000'
65+
WP_SITEURL="${WP_HOME}/wp"
4266
```
4367

44-
### With docker
68+
### 3. Start the stack
69+
70+
**With Docker:**
4571

46-
You can configure your environment variables in the `.env.local` file. By default, the Docker stack is configured to use the following environment variables:
72+
```bash
73+
docker compose up -d
74+
```
4775

48-
### Without docker
76+
The site is available at `http://127.0.0.1:8000`.
4977

50-
You can configure your environment variables in the `.env.local` file.
78+
**Without Docker:**
5179

52-
```bash
53-
PROJECT_NAME='octa'
80+
Point your web server to the `public/` directory and configure your local database, then update `.env.local` accordingly:
5481

82+
```env
5583
DB_HOST='localhost'
56-
DB_NAME='database_name'
57-
DB_USER='database_user'
58-
DB_PASSWORD='database_password'
5984
```
6085

61-
### Start the development server
86+
### 4. Development
6287

6388
```bash
64-
docker compose up -d
89+
pnpm dev
90+
```
91+
92+
Starts the Vite dev server with HMR.
93+
94+
## Project Structure
95+
6596
```
97+
app/
98+
├── Providers/ # Service providers (assets, blocks, theme)
99+
└── View/
100+
└── Composers/ # Blade view composers
101+
bedrock/
102+
├── application.php # WordPress bootstrap & config
103+
└── environments/ # Per-environment overrides (development, staging)
104+
config/ # Acorn config (theme, ACF, mail, prettify…)
105+
resources/
106+
├── css/ # Tailwind CSS (app, editor, blocks/)
107+
├── js/ # TypeScript (app, editor)
108+
├── views/ # Blade templates
109+
├── fonts/
110+
└── images/
111+
public/
112+
├── build/ # Vite output (manifest.json)
113+
├── content/ # Plugins, mu-plugins, uploads
114+
└── wp/ # WordPress core (never edit)
115+
helm/ # Kubernetes Helm chart
116+
routes/ # Custom route definitions
117+
```
118+
119+
## Commands
120+
121+
### Development
122+
123+
| Command | Description |
124+
|---------|------------|
125+
| `pnpm dev` | Vite dev server with HMR |
126+
| `pnpm build` | Production build to `public/build/` |
127+
128+
### Linting
129+
130+
| Command | Description |
131+
|---------|------------|
132+
| `pnpm lint` | Lint JS/TS with ESLint |
133+
| `pnpm lint:fix` | Auto-fix JS/TS lint errors |
134+
| `composer lint` | Lint PHP with Laravel Pint (PSR-12) |
135+
| `composer lint:fix` | Auto-fix PHP lint errors |
136+
137+
### i18n
138+
139+
| Command | Description |
140+
|---------|------------|
141+
| `pnpm translate` | Generate `.pot` and update `.po` files |
142+
| `pnpm translate:compile` | Compile `.mo` and JSON translations |
143+
144+
### Docker
145+
146+
| Command | Description |
147+
|---------|------------|
148+
| `docker compose up -d` | Start stack (MariaDB + PHP + Nginx) |
149+
| `docker compose down` | Stop stack |
150+
151+
## Architecture
152+
153+
### Assets
154+
155+
Vite compiles `resources/` to `public/build/`. The manifest is handled by `AssetsServiceProvider`. Path aliases available:
156+
157+
- `@scripts` → `resources/js`
158+
- `@styles` → `resources/css`
159+
- `@fonts` → `resources/fonts`
160+
- `@images` → `resources/images`
161+
162+
### Theme Configuration
163+
164+
Theme supports, menus, and image sizes are configured in `config/theme.php` and registered by `ThemeServiceProvider`.
165+
166+
`theme.json` is auto-generated by `@roots/vite-plugin` from your Tailwind config and the base `theme.json` file.
167+
168+
### Blocks
169+
170+
Block-specific CSS goes in `resources/css/blocks/` and is dynamically enqueued by `BlockAssetsServiceProvider`.
171+
172+
Custom editor blocks, formats, variations, and plugins are registered from `resources/js/editor/`.
173+
174+
### Environment Config
175+
176+
Environment variables are loaded from `.env` (and `.env.local` override) via Dotenv in `bedrock/application.php`. Per-environment overrides live in `bedrock/environments/`.
177+
178+
### WordPress Plugins
179+
180+
All plugins are managed via Composer (`wpackagist-plugin/*`) and installed to `public/content/plugins/`. Never install plugins manually.
181+
182+
## Code Style
183+
184+
### PHP
185+
186+
PSR-12 enforced by [Laravel Pint](https://laravel.com/docs/pint) — see `pint.json`.
187+
188+
### JavaScript / TypeScript
189+
190+
[ESLint v9](https://eslint.org/) with flat config — see `eslint.config.js`:
191+
192+
- Single quotes, no semicolons
193+
- 2-space indent
194+
- Trailing commas on multiline
195+
196+
### Editor
197+
198+
`.editorconfig` ensures consistent formatting across editors (2-space for JS/JSON/YAML, 4-space for PHP).
199+
200+
## Docker Services
201+
202+
| Service | Image | Port |
203+
|---------|-------|------|
204+
| database | mariadb:11.4 | 3306 (internal) |
205+
| wordpress | wodby/wordpress-php:8.4 | — |
206+
| frontend | wodby/nginx | 8000 |
207+
| mailer | mailpit | 1025 / 8025 |
208+
209+
## CI/CD
210+
211+
GitHub Actions runs on every PR and push to `main`:
212+
213+
- **PHP**: Composer install + `pint --test`
214+
- **Node**: pnpm install + `eslint` + `vite build`
215+
216+
## Deployment
217+
218+
The `Dockerfile` provides a multi-stage production build:
219+
220+
1. Node dependencies + Vite build
221+
2. Composer install (no-dev)
222+
3. Final image based on `inrage/docker-wordpress:8.4-redis`
223+
224+
A Helm chart is available in `helm/` for Kubernetes deployments.
225+
226+
## License
227+
228+
[MIT](LICENSE) - [inRage](https://www.inrage.fr)

0 commit comments

Comments
 (0)