Installation

Overview

This section explains how to install ValPress 1.x on a typical Linux, macOS, or Windows (WAMP/XAMPP) stack. The recommended approach is the ValPress Web Installer, a browser-based wizard that checks your server environment, downloads the latest CMS release from the ValPress API, and guides you through database and site configuration. A separate developer installation path is also documented for teams working from source.

Why It Matters

• A correct installation ensures stable performance, security, and smooth updates.
• Proper file permissions and environment variables prevent runtime errors (caching, uploads, sessions).
• Choosing the right database driver early avoids migration and collation issues later.

How It Works

ValPress is a Laravel application. The Web Installer is a standalone package you upload to your website root. When you open /installer/ in a browser, the wizard:

1. Fetches the latest release requirements from api.valpress.net.
2. Verifies PHP version, extensions, disk space, and directory permissions.
3. Downloads and extracts the ValPress CMS archive into your website root.
4. Collects site URL, site name, administrator account, and database credentials.
5. Creates the .env file and runs the ValPress installation.

After a successful install, you should delete the installer directory for security. ValPress serves pages from the public/ directory; the installer also creates root redirect rules for hosts where pointing the document root at public/ is not immediately possible.

Key components involved:

• Laravel HTTP kernel, configuration, and caches
• Database connection (PDO drivers for MySQL/MariaDB, PostgreSQL, SQLite, or SQL Server)
• Writable website root and ValPress directories (storage, bootstrap/cache, public/uploads)
• Outbound HTTPS access to api.valpress.net (required by the installer to fetch release info and download the CMS)

Usage

Follow these steps depending on your scenario.

1) System requirements

Server requirements (verified by the installer):

• PHP: 8.2 or newer
• Extensions: the installer checks required extensions for the latest release (commonly including bcmath, ctype, dom, fileinfo, filter, gd, gmp, hash, intl, json, libxml, mbstring, openssl, pcre, pdo, session, tokenizer, xml, zip, zlib, and ZipArchive)
• Database (choose one):
  • MySQL >= 5.7 or MariaDB >= 10.3
  • PostgreSQL >= 10.0
  • SQLite >= 3.8.8
  • SQL Server 15+ (via pdo_sqlsrv)
• Web server: Apache or Nginx
• Outbound HTTPS to api.valpress.net
• Writable website root directory

Additional requirements for developer (source-based) installs:

• Composer
• Node.js and npm (if building frontend assets from source)

2) Web Installer (recommended)

Step 1 — Download the installer

Download the installer package from https://valpress.net and extract it on your computer.

Step 2 — Upload to your website root

Upload the entire installer folder to the root directory of your website — the same folder where ValPress CMS will live.

public_html/                  ← your website root
└── installer/
    ├── index.php
    ├── config.php
    ├── includes/
    └── res/

Important: Upload the contents so that index.php is inside the installer folder, not nested one level too deep.

Step 3 — Set permissions

Ensure the website root is writable by the web server. On Linux hosting, 755 for directories is typical. Your host's documentation can confirm the correct permissions.

Step 4 — Open the installer

Visit:

https://yourdomain.com/installer/

If your site lives in a subdirectory, include that path (for example, https://yourdomain.com/my-site/installer/).

Step 5 — Follow the wizard

On success, log in with the administrator account you created during setup.

Step 6 — Secure your installation

• Delete the installer directory after installation completes (the final wizard step offers a one-click delete, or remove it manually via FTP/SFTP).
• Point your web server to public/ (recommended). ValPress serves pages from public/; root index.php and .htaccess redirect rules are created for hosts where changing the document root is not possible.

3) Developer installation (from source)

Use this path when contributing to ValPress or developing against a Git checkout:

1. Clone the ValPress repository into your project directory.
2. Install PHP dependencies: composer install.
3. Install and build assets (if needed): npm install && npm run build.
4. Copy .env.example to .env and configure your database and app settings.
5. Generate an application key: php artisan key:generate.
6. Run migrations (and seeders if desired): php artisan migrate and optionally php artisan db:seed.
7. Link storage: php artisan storage:link.
8. Run php artisan serve for local development, or configure Apache/Nginx to point to public/.

Code Examples

Example 1 — Minimal production .env templates

The Web Installer creates .env automatically. The templates below are useful for developer installs or manual adjustments.

# .env (MySQL/MariaDB)
APP_NAME="ValPress"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://example.com

LOG_CHANNEL=stack
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=valpress
DB_USERNAME=valpress
DB_PASSWORD=change_this

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync
FILESYSTEM_DISK=public

# .env (PostgreSQL)
APP_NAME="ValPress"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://example.com

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=valpress
DB_USERNAME=valpress
DB_PASSWORD=change_this

# .env (SQLite — development/testing)
APP_ENV=local
APP_DEBUG=true

DB_CONNECTION=sqlite
DB_DATABASE=database/database.sqlite

Create the SQLite file if using disk-backed SQLite:

mkdir -p database && touch database/database.sqlite

Example 2 — Apache VirtualHost (DocumentRoot to public/)

<VirtualHost *:80>
    ServerName example.local
    DocumentRoot "/var/www/valpress/public"

    <Directory "/var/www/valpress/public">
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/valpress-error.log
    CustomLog ${APACHE_LOG_DIR}/valpress-access.log combined
</VirtualHost>

Example 3 — Nginx server block (Laravel-friendly)

server {
    listen 80;
    server_name example.local;
    root /var/www/valpress/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
    }

    location ~* \.(?:css|js|jpg|jpeg|gif|png|svg|ico|woff2?)$ {
        try_files $uri =404;
        expires 7d;
        access_log off;
    }
}

Example 4 — First-run CLI (developer method)

php -v                       # Verify PHP >= 8.2
composer install             # Install dependencies
cp .env.example .env         # Configure environment
php artisan key:generate     # Generate APP_KEY
php artisan migrate --force  # Create schema
php artisan db:seed --force  # Optional: seed initial data
php artisan storage:link     # Expose storage/public

Example 5 — Windows (PowerShell, development)

php -v
copy .env.example .env
php artisan key:generate
php artisan migrate
php artisan serve

Advanced Usage

• Non-root web paths (subdirectory installs): Set the site URL correctly during the installer Settings step (for example, https://example.com/cms). If adjusting manually later, update APP_URL in .env and ensure rewrite rules route to public/index.php.
• SQLite for testing: In phpunit.xml or .env.testing, set DB_CONNECTION=sqlite and DB_DATABASE=:memory: for fastest unit tests.
• Dockerized setups: Ensure the container runs PHP 8.2+, mounts storage and bootstrap/cache as writable volumes, and serves /app/public.
• Local development with the installer: On localhost, 127.0.0.1, or domains ending in .local, .test, or .localhost, the installer relaxes SSL verification for API requests automatically. For other local hostnames, set 'verify_ssl' => false in installer/config.php during development only.
• Multi-environment: Maintain separate .env files per environment and use CI secrets to inject credentials. Never commit production .env to version control.

Best Practices

• Use the Web Installer for new production installations unless you have a deliberate reason to deploy from source.
• Point your web server to public/ (never expose the project root).
• Delete the installer directory immediately after a successful installation.
• Keep APP_DEBUG=false in production; enable detailed logs via LOG_LEVEL.
• Use strong DB credentials and least-privilege accounts for production.
• Verify file permissions after deployment; avoid 0777. Prefer www-data:www-data (Linux) ownership with 0644 files and 0755 directories.
• Back up the database and storage/ before updates; test changes on staging.

Common Mistakes

• Leaving the installer online: The installer directory must be removed after installation. It can modify your site configuration if left accessible.
• Serving the app from the project root instead of public/: Exposes secrets and vendor files. Fix: point Apache/Nginx to the public/ directory.
• Blocked outbound HTTPS: The installer cannot reach api.valpress.net. Confirm your server allows outbound HTTPS and that no firewall blocks the API host.
• Missing PHP extensions: Especially intl, mbstring, pdo_*, or ZipArchive. Fix: enable the missing extensions and restart PHP-FPM/Apache.
• Incorrect DB collation/charset: Causing migration or index-length errors. Fix: use utf8mb4/utf8mb4_unicode_ci (MySQL/MariaDB) and recreate schema if needed.
• Insufficient write permissions: On storage/, bootstrap/cache/, or the website root leading to 500 errors. Fix: set correct ownership and chmod -R 755 (no 777).
• Forgetting to set APP_KEY (developer installs): Breaks encrypted cookies and sessions. Fix: run php artisan key:generate and clear caches.

Installer troubleshooting

Summary

Install ValPress using the Web Installer downloaded from https://valpress.net. The wizard verifies your environment against the latest release requirements, downloads the CMS from the ValPress API, configures your site, and completes setup. Delete the installer when finished, serve from public/, and keep production APP_DEBUG disabled. Developer installs from source remain available for local development and contribution workflows.

Compatibility note (1.x): Installer requirements are fetched from the ValPress API at install time and may change between releases. Future 2.x releases may bump the minimum PHP version or adjust required extensions. Follow release notes for any breaking changes in the installation flow.