NewsPilot Documentation

1 Product Overview

NewsPilot is a complete publishing CMS for news, blog and magazine websites. It includes editorial workflow, AI writing tools, multilingual content, SEO tools, reader portal, newsletter, ads, logs and privacy tools.

2 Server Requirements

Required PHP Extensions

• BCMath
• Ctype
• cURL
• DOM
• Fileinfo
• GD (recommended — image thumbnails)
• JSON
• Mbstring
• OpenSSL
• PDO
• PDO MySQL
• Tokenizer
• XML
• Zip

3 Installation Guide

No Node.js or Composer is required: dependencies and front-end assets ship pre-built. Tested on Apache 2.4 + PHP 8.3 + MariaDB/MySQL in production mode; any standard Laravel host (e.g. DigitalOcean via Cloudways, Nginx) works the same way.

cp .env.example .env          # then edit it (step 3)
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force   # roles, settings, languages + your first Super Admin
php artisan storage:link
php artisan optimize

Sign in at https://your-domain.com/login with the ADMIN_EMAIL / ADMIN_PASSWORD you set, then remove ADMIN_PASSWORD from .env. You can create or reset a Super Admin at any time with:

php artisan newspilot:create-admin

Nginx

Use the standard Laravel configuration with root /path-to-project/public; and add this rule so uploaded files can never be executed:

location ~* ^/storage/.*\.(php|phtml|phar|php\d)$ { deny all; }

On Apache this is handled automatically by the included .htaccess files.

Demo content (optional)

To load sample posts, users and ads on a test install, set SEED_DEMO_DATA=true before running php artisan db:seed --force. Never do this on a live site. The demo accounts (password password, e.g. admin@demo.com and the reader visitor@demo.com) are listed at the end of the seed output; your ADMIN_EMAIL account is only created when no Super Admin exists yet, so on a demo install sign in with a demo account.

4 Basic Configuration

APP_NAME="NewsPilot"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

# First Super Admin (remove the password after installing)
ADMIN_EMAIL=you@your-domain.com
ADMIN_PASSWORD=a-long-unique-password

FILESYSTEM_DISK=public
QUEUE_CONNECTION=sync          # no queue worker needed
SESSION_ENCRYPT=true
SESSION_SECURE_COOKIE=true     # once the site runs on HTTPS

# Behind Cloudflare or a load balancer? (see below)
TRUSTED_PROXIES=

DEMO_MODE=false
SEED_DEMO_DATA=false

Behind Cloudflare, a CDN or a load balancer

Set TRUSTED_PROXIES=* (only when your server accepts traffic exclusively through the proxy) or a comma-separated list of the proxy IP ranges. Without it every visitor appears to have the proxy's IP address, so rate limits, login throttling and logs would treat all visitors as one person, and "Force HTTPS" cannot detect secure requests.

Email

Configure SMTP in Admin → Settings → Email & SMTP (the password is stored encrypted). Leave the SMTP host empty to use the MAIL_* values from .env instead.

Settings Areas

5 Main Modules

6 AI Setup & Usage Guide

NewsPilot includes built-in AI tools for article writing, paragraph rewriting, SEO metadata (title, description, tags, slug, social text) and translation. They are available under AI Studio in the admin menu and inside the post editor. Supported providers: OpenAI and Google Gemini (Gemini's free tier works).

Available AI Features

Step 1: Open AI Provider Settings

Login as admin and go to:

Admin Panel → Settings → AI Providers

From this page, the admin can configure AI provider credentials and AI behavior.

Step 2: Add API Keys

• Add your OpenAI API key if you want to use OpenAI.
• Add your Gemini API key if you want to use Gemini.
• API keys are stored in encrypted settings fields.
• Only authorized admin users should manage AI provider keys.

Step 3: Choose Provider & Model, Then Test

Step 4: Use AI Inside Post Editor

Open the post create or edit page:

Admin Panel → Posts → Create Post
Admin Panel → Posts → Edit Post

Inside the post editor, the AI Assistant bar offers three tools (shown according to the user's AI permissions):

• Generate Article: replace the whole article or add the text at the end.
• Generate SEO: fill meta title, meta description, slug, SEO keywords and focus keyphrase.
• Rewrite: paste a paragraph from the article; Replace the original paragraph swaps only that paragraph.
• AI Translate from Default: on a non-default language tab, translates title, excerpt and content (asks before replacing existing text).

The assistant writes in the language of the open tab.

How to Generate an Article with AI

How to Use AI SEO Generator

Two ways to generate SEO metadata:

• In the post editor: Generate SEO → Apply to SEO fields (suggested tags go into the SEO keywords).
• Standalone: AI Studio → SEO Generator, enter a headline (and excerpt), copy the results.
• Results: meta title (≤ 60), meta description (≤ 160), focus keyphrase, slug, tags, Open Graph title and description.
• Always review the output before saving the post.

AI Prompt Templates

Every AI feature uses an editable, versioned prompt template (article, news article, SEO, rewrite, translation). English and Bangla templates are included; for other languages the English template is used and the AI is told to answer in the post's language.

AI Studio → Prompt Templates

AI Usage Reports

Admin can monitor AI usage, provider status, token/cost tracking and recent errors from:

AI Studio → Usage Reports

AI on a Public Demo Site

With DEMO_MODE=true in .env, visitors can try AI with your key while demo data stays read-only:

• Each visitor (IP) gets AI_DEMO_REQUESTS_PER_HOUR AI requests per hour (default 10).
• Articles are limited to AI_DEMO_MAX_WORDS words (default 400).
• If the key's quota runs out, visitors see sample text marked "[Demo AI]" instead of an error.
• Use a key from a separate Google Cloud project without billing (Gemini free tier), restricted to the Gemini API and your server's IP, so it can never cost money.

AI Troubleshooting

7 Cron Job & Scheduler

Add one cron entry; Laravel runs the tasks below on their own schedule.

* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1

8 Roles & Permissions

NewsPilot uses Spatie Laravel Permission for role-based access control.

• Built-in roles: Super Admin, Admin, Editor, Author, Contributor, SEO Manager, Ad Manager, Employee, Subscriber
• Permission groups for organized access control
• Assign roles and individual permissions from the admin panel
• Menus and actions are shown only to users with the matching permission
• New staff receive an e-mail link to set their own password

9 Visitor Portal

Reader accounts (sign-up)

Visitors create a free reader account at /register (linked from the login page, the header, the footer and the comment box). Sign-up always creates a reader; staff accounts are still invited from Staff in the admin.

• Turn sign-up on or off in Settings → Security → Allow Reader Sign-up (on by default). When it is off, /register returns 404 and the links disappear.
• Spam protection: a hidden honeypot field and a limit of 5 sign-ups per IP address per hour. CAPTCHA (Cloudflare Turnstile / reCAPTCHA) is planned for 3.4.
• Readers choose their article font size and reading width in Settings → Appearance, and which events notify them in Email & Newsletter → Preferences.

10 Public Frontend

• Home page with breaking news, hero and latest articles
• Post details with reading actions and related posts
• Category, tag and author pages
• Search page
• Newsletter sign-up and ad placements
• Multi-language URLs with hreflang and canonical tags
• SEO metadata and schema output
• Local placeholder images in the category colour when a post has no image

Ad placements

Create a creative in Ad Manager and assign it to one of these zones. A zone that is off, or has no active creative within its dates, prints nothing. Image ads need an image; HTML ads accept your ad network code.

Impressions are counted when at least half of the ad is on screen (crawlers excluded, max. 30 per visitor per creative per hour). Clicks go through /ads/click/{id} and are rate limited. Theme developers can add their own zone with <x-frontend.ad-zone zone="your_key" />.

Redirects

SEO Tools → Redirects sends an old path (for example /old-article) to a new path or full URL with 301, 302, 307 or 308, keeping the query string if you choose. Admin, sign-in and system paths cannot be redirected. When the slug of a published post or page changes, a 301 from the old URL is created automatically (can be turned off in Settings → SEO Defaults).

Translating the theme

The theme's own words (menus, buttons, headings, messages) follow the visitor's language. Bangla, Arabic, Spanish, French and Hindi are included in lang/. To add a language, add it in Languages, copy lang/es.json to lang/<code>.json (for example de.json), translate the values and run php artisan optimize:clear. Missing entries fall back to English. Text you type in the admin (site name, tagline, copyright) is shown as written.

11 Update Guide

1. Back up your database and the storage/ folder.
2. Upload the new files, except .env and storage/ (keep yours).
3. Run:

php artisan migrate --force
php artisan optimize:clear
php artisan optimize

12 Troubleshooting

13 Security

• Laravel CSRF protection, bcrypt password hashing and policy / permission checks on every admin action
• Two-factor authentication (TOTP) with recovery codes for every account; can be required for all staff
• Login throttling per e-mail + IP and per IP (configurable)
• Rate limits on comments, reactions, newsletter sign-ups and ad-click counting
• Article, page and AI content sanitised with HTMLPurifier; comments are always escaped
• Uploads validated by real file content; stored extension derived from the detected type; SVG / HTML / PHP refused; scripts can never run from the upload folder
• Security headers: X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, HSTS on HTTPS (config/security.php)
• Encrypted storage for API keys and the SMTP password; optional encrypted sessions
• No encrypted / obfuscated code, no licence server and no calls to the author's servers

14 Changelog

3.3.0 — October 2026

See CHANGELOG.md in the package for the full list. Highlights:

• Security: working two-factor authentication, upload hardening, XSS fixes, rate limiting, security headers
• Fixed: dark mode lost on navigation, media library freezing, "Phase 4B" placeholder replaced by a full post detail page, staff invitations, SEO title/description/schema missing on article pages
• Settings: SEO, analytics, social, comments, security and SMTP settings now apply; unused settings removed from the admin
• Install: no Node.js required, first-admin command, Cloudflare / proxy support
• Also fixed: editor opening empty on existing posts, ads never displayed, redirects never applied, branding missing on the public site, Quick Create shortcuts
• New: reader sign-up, public theme in 5 more languages, hreflang + canonical tags, automatic 301 on slug change, viewable ad impressions, local image placeholders
• Reader portal: privacy settings enforced, reader profiles, follow-publish notifications that link to the article, appearance settings applied
• AI: clear errors instead of placeholder text when a key is missing or wrong, a model setting per provider with current defaults, Test connection, SEO Generator fixed, long translations, Rewrite replaces only the paragraph, AI in every site language, Gemini free tier supported, safe AI on a live demo

15 Support Policy

For support, contact through the CodeCanyon support tab with purchase code and issue details.

Support Includes

• Bug reports related to original product files
• Installation guidance based on documentation
• Clarification about existing features
• Basic configuration help

Support Does Not Include

• Custom feature development
• Third-party plugin customization
• Unrelated server management
• Unsupported hosting environment issues