README

Blogging and Small Business CMS

Pubvana v2 is a full rewrite of Pubvana v1.x built on CodeIgniter 4, Authentication with Shield, a modern admin UI, dual content editors, theme, plugin & widget system, built-in marketplace, and many new features. We aim for Pubvana to be lean and fast without the bloat of other CMS and Blog software available.

These instructions are for users comfortable with the command line and terminal. If you'd prefer a streamlined experience, [go here: placeholder].

Installation

1. Prerequisites

Before installing, make sure you have:

• PHP 8.2+ with required extensions (see Requirements below)
• Composer (getcomposer.org)
• MySQL 5.7+ or MariaDB 10.3+
• A web server (Apache with mod_rewrite, or Nginx)

Create an empty MySQL database and a user with full privileges on it. You'll need the database name, username, and password for the next steps.

2. Download

For Production : for site owners deploying Pubvana as is:

Navigate to the directory you wish to use for the project root.

  cd ~/public_html/

Install Pubvana from Packagist. (Note the '.' to install into your current directory)

composer create-project enlivenapp/pubvana .

For Development : for contributors who want to run tests, build additional features and work on the codebase:

  git clone https://github.com/enlivenapp/pubvana.git
  cd pubvana
  composer install

The remaining steps apply to production and development environments.

3. Configure

Open the sample environment file in a text editor or Vim/Nano:

  Edit these lines at a minimum: (uncomment (remove #))

  CI_ENVIRONMENT = production  # or development

  app.baseURL = 'https://your-domain.com/'

  database.default.hostname = localhost
  database.default.database = your_database_name
  database.default.username = your_database_user
  database.default.password = your_database_password

  Set CI_ENVIRONMENT to production for a live site or development for local
  work.  Leaving this commented defaults to the production environment

Save this file as .env

4. Initialize

On the command line run these three commands separately.

php spark key:generate
php spark migrate --all
php spark db:seed DatabaseSeeder

5. Web Server

Point your web server to the public/ folder. https://your-server/path-to-pubvana. You should see the homepage of your new website.

6. Log In

Visit https://your-server/path-to-pubvana/login.

Default admin login — admin@example.com / Admin@12345 — change password immediately after first login.

7. File and Directory Structure

Your web hosts serves files from the directory where index.php lives Detailed Information. Pubvana uses the default CodeIgniter ~DOC_ROOT/public/ setup and attempts to forward traffic to /public/index.php with clean URLs. To increase security or if an .htaccess won't be honored (Nginx), you can change where these files reside on the server or edit your Nginx config file. Check the link above for detailed information how to move core files outside the web root, index.php into the root folder public_html on shared servers.

8. Web Server User

Pubvana needs to create symlinks and write files on behalf of your web server. The following steps require you to know which user your web server runs as. If you already know, skip ahead to Step 9.

cPanel, DirectAdmin or shared hosting:

Your web server runs as your account username, the same user you are logged in as. Files you create are already owned by the correct user, so you can skip the chown ownership commands in the following steps.

VPS or dedicated server:

You manage the web server yourself. The user depends on your OS and web server:

You can confirm by checking your web server's configuration file. For Apache, look for the User directive in /etc/apache2/apache2.conf or /etc/httpd/conf/httpd.conf. For Nginx, look at the user line near the top of /etc/nginx/nginx.conf.

Not sure what web server you have?

Ask your hosting provider. Common web servers are Apache, Nginx, and LiteSpeed. Many cPanel hosts use LiteSpeed but display "Apache" in the control panel, DirectAdmin favors PHP-FPM. Either way, on cPanel/DirectAdmin the user is your account username.

Keep this username handy. You will need it in the next steps.

9. Theme Assets Symlink

Theme CSS, JS, and images are stored in themes/{folder}/assets/ under the project root, which is outside the document root. A symlink (symbolic link) is a shortcut that makes files from one location accessible at another without copying them. Pubvana uses symlinks inside the document root pointing to each theme's assets so browsers can load them.

Pubvana attempts to create these automatically when you visit Admin → Themes or activate a theme. Each symlink looks like a regular directory but it points to another directory:

{document root}/themes/default  →  {project root}/themes/default/assets

On shared hosting you'll often see a www "directory", this is a symlink to the public_html directory. This is what we're doing here.

First, give your web server user (from Step 8) write access to the themes/ directory inside your document root:

chown yourwebuser:yourwebuser /path/to/docroot/themes/

If this returns Operation not permitted, prefix with sudo:

sudo chown yourwebuser:yourwebuser /path/to/docroot/themes/

then enter your password.

On cPanel, DirectAdmin or shared hosting you can skip this, as files are already owned by your account user.

Once ownership is set, visit Admin → Themes and activate your theme. Pubvana will create the symlink automatically. If your theme's CSS and images are loading, you are all set.

If the symlink was not created (styles are missing, images are broken), create it manually:

ln -s /path/to/project/themes/default/assets /path/to/docroot/themes/default

Replace default with your theme's folder name and adjust both paths to match your layout.

10. Media Uploads Symlink

Uploaded images (avatars, featured images, media library) are stored in writable/uploads/ under the project root — also outside the document root. A symlink exposes only the uploads/ subdirectory to browsers while keeping sessions, cache, and logs private.

Quick troubleshooting: If writable/sessions, writable/cache, and writable/logs (and often database errors) are not writable by the web user CodeIgniter will give the white screen of death when the environment is set to production. You may find the exact reason in the webserver's logs(not CodeIgniter's). If you're having significant trouble diagnosing the issue, set CI_ENVIRONMENT = development temporarily in your .env file which will show the debug bar and (likely) the exception causing the issue. CodeIgniter Doc - Running Your App | CodeIgniter Troubleshooting

{document root}/writable/uploads  →  {project root}/writable/uploads

Create this once after installation:

mkdir -p /path/to/docroot/writable
ln -s /path/to/project/writable/uploads /path/to/docroot/writable/uploads

Note: Apache must follow symlinks for both steps 9 and 10 to work. Pubvana's .htaccess already includes Options +FollowSymlinks.

CLI Commands

Cron Jobs

Scheduled post publishing requires a cron job. Add to crontab by command line:

* * * * * path/to/php /path/to/pubvana/spark posts:publish >> /dev/null 2>&1

Often it's easier to create Crons in your web control panel (CPanel/DirectAdmin). To help:

• * * * * * are the time slots.
• path/to/php /path/to/pubvana/spark posts:publish Command to run
• dev/null 2>&1 fancy way to say throw it away. You have more choices in your control panel.

Run path/to/php /path/to/pubvana/spark links:check as needed (e.g. weekly) — to automate checking for broken links, results appear in Admin → Broken Links.

Requirements

• PHP 8.2+
• MySQL 5.7+ / MariaDB 10.3+
• Composer (highly recommended)
• Apache mod_rewrite (or Nginx equivalent)
• PHP extensions: intl, mbstring, json, mysqlnd, gd, zip

Stack (v2)

Features (v2)

• Posts & Pages with draft/published/scheduled workflow
• Dual content editor — WYSIWYG HTML or Markdown, selectable per post
• Theme system with widget areas, theme options, and asset symlinking
• 8 built-in widgets with drag-and-drop area management
• Configurable front page — blog index or any static page
• Marketplace — browse and install free themes & widgets (live API + cache + mock fallback)
• Role-based access — superadmin, admin, editor, author, subscriber
• Media library with auto-generated thumbnails
• Navigation manager with drag-and-drop reordering
• Comment moderation — approve, spam, or trash
• SEO — per-post meta, sitemap.xml, RSS feed, Google Analytics
• 301/302 redirect manager
• Social links manager
• Author profiles with bio cards on posts
• Social OAuth login (Google, Facebook)
• Social auto-share on publish (Twitter, Facebook)
• WordPress importer (admin UI + php spark wp:import CLI)
• Post revision history with one-click restore

Security

Reporting a Vulnerability

Please do not open a public issue for security vulnerabilities. Email security reports to cs@pubvana.net. We aim to respond within 48 hours and will credit reporters in the changelog.

hCaptcha (Spam Protection)

Pubvana uses hCaptcha (privacy-respecting, non-Google) to protect comment forms and the contact form from spam bots. hCaptcha is free for most sites.

Setup:

1. Sign up at hcaptcha.com (free)
2. Create a new site and copy the site key and secret key
3. Add to your .env:

HCAPTCHA_SITE_KEY = your-site-key
HCAPTCHA_SECRET_KEY = your-secret-key

If these keys are not set, hCaptcha is silently skipped — safe for local development. Once configured, the widget appears automatically on the comment form and contact page.

Production Hardening Checklist

Before deploying to a public server:

• Set CI_ENVIRONMENT = production in .env — disables stack traces and debug output
• Change the default admin password (admin@example.com / Admin@12345) immediately after first login
• Set app.baseURL to your actual domain in .env
• Set app.forceGlobalSecureRequests = true in app/Config/App.php to enforce HTTPS and send HSTS headers
• Enable CSP: set app.CSPEnabled = true in app/Config/App.php and configure a policy appropriate to your theme
• Ensure only writable/uploads/ is web-accessible (via the symlink above) — never symlink or move writable/ itself into public/, as it contains sessions, cache, and logs
• Ensure .env has permissions 600 and is not committed to version control
• Run php spark key:generate once per installation — do not reuse encryption keys across sites
• Set chown www-data:www-data public/themes/ so only the web server can create theme symlinks

Content Security Note

Post, page, and widget content is stored and rendered as raw HTML. This is intentional — administrators are trusted to write HTML directly. If your site allows editors or authors to submit HTML content, consider adding server-side HTML sanitization (e.g. HTML Purifier) to your post-save pipeline before rendering untrusted content.

Security Fixes Log

Bug Reports & Feature Requests

Please use the Issues Tracker.

Links

pubvana.net — Home & Addon Store (Themes, Widgets, and other Addons)

User Docs

Facebook Page

License

Pubvana is released under the MIT Open Source License.

Contributors & Team Members

• Enliven Applications

Translators & Translations

Translators Wanted!

If you would like to help translate files, please fork this repo and send a PR.

v2 ships with 6 languages: English (source), French, Indonesian, Portuguese, Slovak, and Spanish (Latin American). All non-English translations were AI-generated and need verification from native speakers. 16 additional languages are seeded in the admin panel but ship without translation files — CI4 falls back to English.

Please include a README.md update under 'Translators' with your name and a link to your site/GitHub (optional).

• French — AI translated, needs native speaker verification

  • v1 contributors: Paul DUBOT, Léonard GAURIAU, Clément TRASSOUDAINE, Jean-Baptiste VALLADEAU, Rhagngahr

• Indonesian — AI translated, needs native speaker verification

  • v1 contributor: Suhindra

• Portuguese — AI translated, needs native speaker verification

  • v1 contributor: Samuel Fontebasso

• Slovak — AI translated, needs native speaker verification

• Spanish (Latin American) — AI translated, needs native speaker verification

Roadmap / Todo

Pubvana Core

Built-in Widgets

• Recent Posts
• Tag Cloud
• Categories List
• Archive List
• Search Form
• Social Links
• Text Block
• Recent Comments
• Table of Contents
• Related Posts

Platform Features

• Author Profiles & Bio Card
• Social OAuth Login (Google, Facebook)
• Social Auto-Share on Publish (Twitter, Facebook)
• Marketplace API with cache + refresh
• WordPress Importer (admin UI + php spark wp:import CLI)
• Post Revision History
• Maintenance Mode toggle
• Core update notifications + php spark pubvana:update CLI
• Content Preview Links (shareable draft URLs)
• Bulk Post Actions (publish / unpublish / delete many)
• Schema.org Markup (Article, BreadcrumbList, Author JSON-LD)
• Image WebP Auto-Convert on Upload
• Multi-language Support (22 languages, admin enable/disable, {locale} URL routing, lang() throughout views)
• Honeypot Spam Protection (CI4 built-in filter on comment + contact forms)
• Atom 1.0 Feed (/atom alongside existing RSS)
• Email Notifications / Subscriptions (subscribe to new posts, email verification, unsubscribe)
• Links Manager / Blogroll (display a curated list of external links via widget)

Pubvana Premium

Premium Core Features (pubvana.net — license required)

• Scheduled Post Queue (calendar view)
• Content Analytics (page views, popular posts, referrers)
• Advanced SEO (OG image generation, schema breadcrumbs, news sitemap)
• Two-Factor Authentication (TOTP)
• Backup & Export (DB + uploads zip)
• Membership / Paywalled Posts
• Affiliate Link Manager (/go/ short links + click tracking)
• Broken Link Checker
• Activity / Audit Log

Premium Widgets (pubvana.net/store)

• Author Bio (sidebar)
• Ad Unit / Custom HTML
• Social Follow Buttons
• Tip Jar / Per-post donations
• Reading Progress Bar
• Enhanced Search (AJAX live preview)
• Email Opt-in / Lead Capture
• Countdown Timer
• Advanced Login
• Gallery (masonry + lightbox)
• Google Calendar & Maps
• YouTube Channel Feed

Premium Plugins (pubvana.net/store)

• E-commerce (products, cart, checkout, orders)