================================================================================
                         GETTING STARTED — QUICK SETUP
================================================================================

Thank you for purchasing this site! Follow these steps to get up and running.


REQUIREMENTS
------------
- PHP 8.5 or higher (with pdo_pgsql, openssl, mbstring, gd, curl extensions)
- PostgreSQL 17 or higher
- A web hosting account with FTP/SFTP access
- Your domain pointed to the /public folder as the web root


STEP 1 — UPLOAD FILES
---------------------
Upload the entire folder structure to your hosting account:

    composer.json   → Project manifest (keep at project root)
    /src/           → Application classes (NOT inside public web root)
    /vendor/        → Composer autoloader and bundled dependencies
    /data/          → Private folder (NOT inside public web root)
    /includes/      → Private folder (NOT inside public web root)
    /public/        → This must be your web root (document root)

IMPORTANT: Only the /public folder should be accessible from the web.
The /data, /includes, /src, /vendor, and composer.json files must stay
above or outside the web root.

IMPORTANT: Upload the included /vendor folder as-is. The site already ships
with Composer dependencies and does not require package installation on the
hosting account.


STEP 2 — CREATE YOUR DATABASE
------------------------------
Create a PostgreSQL database through your hosting control panel.
Note down the following details — you will need them in Step 4:

    - Database host (e.g. localhost or a hostname)
    - Database port (usually 5432)
    - Database name
    - Database username
    - Database password

IMPORTANT: The database user must have FULL privileges on the database
(CREATE, SELECT, INSERT, UPDATE, DELETE, ALTER, DROP). The site needs
these to create tables, run migrations, and operate normally.

If you are using a hosting control panel (cPanel, Plesk, etc.):
    - Create a new database
    - Create a new database user with a strong password
    - Assign the user to the database with "ALL PRIVILEGES"

If you have direct PostgreSQL access:
    CREATE DATABASE your_db_name;
    CREATE USER your_user WITH PASSWORD 'your_password';
    GRANT ALL PRIVILEGES ON DATABASE your_db_name TO your_user;
    ALTER DATABASE your_db_name OWNER TO your_user;

If setup fails with a "permission denied" error, ask your hosting
provider to grant your database user full read/write permissions,
or to make it the owner of the database.


STEP 3 — MOVE SETUP FILE
--------------------------
Using FTP or your hosting file manager, move (or copy) this file:

    FROM:   /data/setup.php
    TO:     /public/setup.php

This makes the setup wizard accessible from your browser.


STEP 4 — RUN THE SETUP WIZARD
-------------------------------
Open your browser and visit:

    https://yourdomain.com/setup.php

If your site is installed in a subfolder, use that path instead:

    https://yourdomain.com/your-subfolder/setup.php

The wizard will:
    1. Test your database connection
    2. Create all required tables automatically
    3. Let you create your admin account
    4. Add your IP to the admin allowlist
    5. Generate the /data/config.json file
    6. Automatically move setup.php back to /data for security

Notes:
        - If an "admin" account already exists from bootstrap, the wizard
            safely updates that account's password when you choose username "admin".
        - If the wizard cannot remove /public/setup.php automatically, delete it
            manually right after setup.


STEP 5 — LOG IN
-----------------
After setup completes, visit:

    https://yourdomain.com/admin

If installed in a subfolder:

    https://yourdomain.com/your-subfolder/admin

Log in with the admin username and password you created in Step 4.


================================================================================
                              FOLDER STRUCTURE
================================================================================

/data/                      Private data (NOT web accessible)
  ├── config.json           Created automatically by setup wizard
  ├── config.example.json   Reference file for manual configuration
  ├── setup.php             Setup wizard (move to /public to use)
  ├── allowlist_tool.php    Emergency IP management tool (see below)
  ├── README.txt            This file
  ├── admin_uploads/        Admin-uploaded files
  ├── chat_images/          Chat image uploads
  ├── contact_uploads/      Contact form attachments
  ├── forum_images/         Forum post images
  ├── profile_photos/       User profile photos
    ├── push_queue/           Push notification queue storage
    ├── refund_uploads/       Refund request attachments
  └── cache/                File-based cache

/includes/                  Bootstrap files (NOT web accessible)
  └── _init.php             Core initialization (session, CSRF, CSP, helpers)

/src/                       PSR-4 classes under NewSite\ namespace
  ├── Admin/                Admin layout
  ├── Auth/                 Admin and site authentication
  ├── Cache/                Cache service and cached queries
  ├── Config/               Configuration loader and setup service
  ├── Database/             Database manager, helpers, schema migrations
  ├── Http/                 Response utilities
  ├── Logging/              Log service and request logger
  ├── Security/             CSRF, IP banning, rate limiting
  ├── Settings/             Site settings service
  ├── Shop/                 Cart, currency, orders, downloads
  ├── Template/             Template and content rendering
  ├── User/                 User, friends, messages, profiles
  └── ...                   Email, Forum, GDPR, Geo, Push, Upload, Util, Visitor

/vendor/                    Composer autoloader (generated)

/public/                    Web root (the ONLY folder accessible via browser)
  ├── index.php             Front controller
  ├── admin/                Admin panel
  ├── assets/               CSS, images, JS
  └── templates/            Page templates


================================================================================
                           IMPORTANT SECURITY NOTES
================================================================================

ADMIN IP ALLOWLIST
    Only IPs added to the allowlist can access /admin.
    Your IP is added automatically during setup.
    To manage IPs, go to: Admin → Settings → IP Allowlist.

IF YOU GET LOCKED OUT
    If your IP changes and you cannot access /admin:
    1. Rename /data/allowlist_tool.php to a random name
       (e.g. fix_8a3f2b.php)
    2. Move it to /public/
    3. Visit https://yourdomain.com/fix_8a3f2b.php in your browser
    4. On first load the tool creates a token file in the SAME folder
       (e.g. /public/allowlist_tool.token)
    5. Open that .token file with a text editor or your hosting
       file manager and copy the token string inside it
    6. Paste the token into the Access Token field and click Unlock
    7. Add your new IP to the allowlist
    8. DELETE BOTH files from /public/ immediately after use
       (the renamed .php file AND the .token file)

CONTENT SECURITY POLICY
    This site uses strict CSP headers. All styles must be in external
    CSS files. No inline styles, no inline JavaScript.

GDPR COMPLIANCE
    GDPR data retention is configurable in Admin → Settings → GDPR.
    Visitor data is automatically cleaned based on your retention settings.

OPTIONAL: OVH SCHEDULED JOBS (CRON) FOR BACKUPS
    If your hosting includes OVH Scheduled Jobs, you can trigger backups
    automatically without SSH access.

    This is OPTIONAL. If you do not configure cron, backups can still run
    from Admin → Backups when due.

    Recommended OVH configuration:
    - Language: PHP 8.5
    - Command to execute: ./public/admin/backup.php
    - Frequency: every 15 minutes (the app interval decides if a backup is due)

    Notes:
    - The app checks Admin → Backups settings:
            backup_enabled, backup_interval_hours, backup_mode,
            backup_scheduler_mode, backup_include_db.
        - In Admin → Backups set Auto backup trigger to:
            * Web trigger (no cron required), or
            * Cron/CLI trigger (OVH Scheduled Jobs or another hosting scheduled PHP task).
    - A backup is only created when the configured interval is due.
    - Cron output "No backup due" is normal between scheduled runs.
    - Keep backup storage outside the web root for security.

PASSWORDS
    All passwords are hashed with Argon2id. Never store plain-text
    passwords anywhere.


================================================================================
                              MANUAL CONFIGURATION
================================================================================

If the setup wizard does not work for any reason, you can configure
the site manually:

1. Copy /data/config.example.json to /data/config.json
2. Edit config.json with your database credentials (see the file for format)
3. Visit any page on your site — the database tables will be created
   automatically on first load
4. A temporary bootstrap admin account is created on first load if no users exist:
       Username: admin
       Password: admin123
5. Log in at /admin and CHANGE THE PASSWORD IMMEDIATELY
6. Add your IP to the allowlist in Settings


================================================================================
                                NEED HELP?
================================================================================

- Check Admin → Info for system status and documentation
- Check Admin → Logs for error messages
- Check Admin → Security Scan to audit your site for issues
- Review config.example.json for database configuration reference

================================================================================
