=====================================================================
 uniThink STAGING - HOW TO PUT THIS ON THE SERVER
=====================================================================

 Written to be followed step by step. Nothing here touches the live
 website. If a step does not match what you see on screen, STOP and
 send a screenshot rather than improvising - one wrong path here is
 the difference between a private staging site and a public one.

 Roughly 30-40 minutes.


---------------------------------------------------------------------
 WHAT YOU ARE BUILDING
---------------------------------------------------------------------

 Two web addresses, one copy of the software:

   https://staging.unithink.co          the public website
   https://admin-staging.unithink.co    the admin panel

 Both point at the SAME folder. The software works out which of the
 two you asked for from the address you typed. This is intended - do
 not give them separate folders.

 The live site at unithink.co is not touched by any step below.


---------------------------------------------------------------------
 STEP 1 - UPLOAD AND EXTRACT
---------------------------------------------------------------------

 1. Log in to cPanel.

 2. Open FILE MANAGER.

 3. Go to your home directory. It is shown at the top left and looks
    like:  /home/fictionh

    Do NOT go into public_html. This does not belong there.

 4. Click UPLOAD and choose the .zip file I sent you.
    Wait for it to reach 100%. It is about 15 MB.

 5. Go back to /home/fictionh. You will see the .zip file.
    Right-click it and choose EXTRACT.

 6. When asked where to extract, leave it as /home/fictionh
    and confirm.

 7. You should now have a folder called:

        unithink-stage

    Open it. You should see: app, bin, config, database, public,
    routes, storage, and three files (.env.example, DEPLOY-README.txt,
    MANIFEST.txt).

 8. Delete the .zip file. You do not need it on the server.


---------------------------------------------------------------------
 STEP 2 - POINT BOTH WEB ADDRESSES AT IT
---------------------------------------------------------------------

 In cPanel, open DOMAINS (called SUBDOMAINS on older versions).

 For staging.unithink.co, set the Document Root to EXACTLY:

        /home/fictionh/unithink-stage/public

 Then do the same for admin-staging.unithink.co - the SAME path:

        /home/fictionh/unithink-stage/public

 Both. The same folder. That is correct and deliberate.

 IMPORTANT: the path ends in /public. If it ends at
 /unithink-stage with no /public, the entire application becomes
 downloadable from the internet, including the file holding your
 database password. If cPanel will not accept a path outside
 public_html, STOP and tell me - do not move the folder to make it fit.


---------------------------------------------------------------------
 STEP 3 - SET PHP TO 8.2
---------------------------------------------------------------------

 In cPanel, open MULTIPHP MANAGER.

 Find staging.unithink.co and admin-staging.unithink.co in the list.
 Tick both. Set PHP Version to 8.2 (or newer). Apply.

 If they are already 8.2, nothing to do.

 (If this is missed, the site shows a plain message telling you the
 PHP version is wrong. That is deliberate, not a crash.)


---------------------------------------------------------------------
 STEP 4 - CREATE THE SETTINGS FILE
---------------------------------------------------------------------

 1. In File Manager, open /home/fictionh/unithink-stage

 2. Turn on hidden files:
    SETTINGS (top right) -> tick "Show Hidden Files" -> Save.

 3. Right-click  .env.example  and choose COPY.
    Copy it into the same folder, then RENAME the copy to exactly:

        .env

    (a dot, then env, nothing else)

 4. Right-click .env and choose EDIT.

 5. Find these two lines and replace the bracketed text with the real
    passwords for the two database users you created:

        DB_PASSWORD=[PASTE THE APPLICATION DB PASSWORD HERE]
        DB_MIGRATE_PASSWORD=[PASTE THE MIGRATION DB PASSWORD HERE]

    Also check these three match what you actually created in cPanel,
    and correct them if not:

        DB_DATABASE=fictionh_unithink_stage
        DB_USERNAME=fictionh_stg_app
        DB_MIGRATE_USERNAME=fictionh_stg_migrate

 6. Save. Close the editor.

 7. Right-click .env -> PERMISSIONS -> set to 600. Save.
    (Only your account can then read it.)

 DO NOT change anything else in that file. In particular there is a
 commented-out line about indexing near the top - leave it commented
 out. It is what keeps this staging copy from competing with the real
 website in Google.


---------------------------------------------------------------------
 STEP 5 - SET FOLDER PERMISSIONS
---------------------------------------------------------------------

 In File Manager, open /home/fictionh/unithink-stage/storage

 For each of the five folders inside - cache, logs, sessions, temp,
 uploads - right-click, choose PERMISSIONS, and set 755.

 Do NOT use 777. It is not needed on this server, and it would let
 any other account on the machine write into your site.


---------------------------------------------------------------------
 STEP 6 - BUILD THE DATABASE
---------------------------------------------------------------------

 In cPanel, open TERMINAL.

 (If there is no Terminal, see the note near the end of this file.)

 Type these commands, one at a time, pressing Enter after each:

        cd /home/fictionh/unithink-stage

        php bin/migrate.php

 You should see a line beginning "SQL mode:", then "Connected to ...",
 then a list of migrations each ending "done", then
 "Applied 26 migration(s)."

 Then confirm:

        php bin/migrate.php status

 Every line should say applied. If any says pending, or if it refuses
 to run at all, send me exactly what it printed.


---------------------------------------------------------------------
 STEP 7 - LOAD THE STARTING DATA
---------------------------------------------------------------------

 Still in Terminal, same folder:

        php bin/seed.php

 This loads settings and the permission list. It is safe to run more
 than once.


---------------------------------------------------------------------
 STEP 8 - CREATE YOUR ADMIN LOGIN
---------------------------------------------------------------------

 Still in Terminal:

    php bin/create-admin.php --email=you@unithink.co --name="Your Name"

 Use your real email address.

 It prints a generated password ONCE. Copy it somewhere safe now - it
 is not shown again and nobody can look it up afterwards. You will be
 asked to change it the first time you sign in.

 The password is generated rather than chosen because a password typed
 into a command is stored in the server's command history.


---------------------------------------------------------------------
 STEP 9 - CHECK IT WORKS
---------------------------------------------------------------------

 Open these in a browser:

  1. https://staging.unithink.co/
     -> the public website. It will be nearly empty until content is
        added. That is expected.

  2. https://admin-staging.unithink.co/
     -> the admin login screen. Sign in with the email and the
        generated password.

  3. https://staging.unithink.co/pages
     -> MUST show "page not found".
        If it shows the admin Pages screen instead, STOP and tell me.
        It would mean the two addresses are not being kept apart.

  4. https://staging.unithink.co/.env
     -> MUST show an error or "not found".
        If it shows text starting with APP_NAME, STOP IMMEDIATELY and
        tell me. The Document Root is wrong and your database password
        is readable from the internet.

  5. https://staging.unithink.co/robots.txt
     -> MUST say "Disallow: /".
        This is what keeps the staging copy out of Google.

 Send me what you see for 3, 4 and 5 either way - including if they
 are correct.


---------------------------------------------------------------------
 IF THERE IS NO TERMINAL IN CPANEL
---------------------------------------------------------------------

 Steps 6 and 7 can be run as temporary cron jobs.

 cPanel -> Cron Jobs -> Add New Cron Job
 Set "Once Per Minute", command:

   cd /home/fictionh/unithink-stage && /usr/local/bin/php bin/migrate.php

 Wait two minutes, then DELETE the cron job. Repeat for bin/seed.php.

 Step 8 prints a password to the screen, so it cannot be run usefully
 this way. Tell me and we will find another route.


---------------------------------------------------------------------
 THINGS THAT SHOULD WORRY YOU
---------------------------------------------------------------------

 * A page listing files instead of the website
       -> Document Root is wrong (Step 2).
 * "This application requires PHP 8.2 or newer"
       -> Step 3.
 * A blank white page
       -> tell me, and look in
          /home/fictionh/unithink-stage/storage/logs/
 * The .env file readable in a browser
       -> STOP. Tell me now.
 * The staging site appearing in a Google search
       -> tell me now.

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