Local Development Setup - Windows

Overview

• This guide assumes you are on Windows. Mac and Linux have different methods.
• Please read every step of this guide carefully. It is highly recommend doing a full read-through before you even get started.

Within this guide, we will be installing the following software:

• Composer for handling PHP packages
• VS Code as our code editor

Windows Firewall Pop-ups

At any point in time while installing the below software, you may see a pop-up like this. Click "Allow" to allow the software to finish installing. All of the recommended software is safe.

Copying Lorekeeper

We are now going to use SourceGit to make a copy of Lorekeeper. This will be your personalized version that is posted to your live website.

1. In SourceGit, select the little cloud icon in the top right to "Clone Repository." "Clone" is the Git term for making a copy of the code.

2. Now we will fill out this field with some information that tells SourceGit where the Lorekeeper code is located. In the browser, it can be accessed here, but we use a slightly different URL address when pasting it into Git.

• For Repository URL, paste in https://github.com/lk-arpg/lorekeeper.git.
• For Parent Folder, this will define where the code exists on our computer. If you installed XAMPP in the directory C:/xampp/, we will be selecting the folder C:/xampp/htdocs. If this folder does not exist, create it.
• Everything else can be left blank.

3. Your window should look like this:

4. Click "OK" to beginning cloning, and the process will begin.

5. You now have a copy of Lorekeeper on your computer! The first thing you will want to do is rename the origin (core Lorekeeper) remote. Click the dropdown for "Remotes", and then right click "origin" and click "Edit".

6. Rename this branch to "lorekeeper", or another similar identifier that will indicate to you that this is where LK updates will come from.

7. Click "OK" to save the change. It should now look like this:

Cloning a Higher Version of LK

As of this writing, the main branch of LK is on version 2.1. You may wish to be on a higher version, such as the release branch version 3.0.

Please note that is extremely discouraged to put your site on the develop branch of Lorekeeper. Please see our dev intro regarding different branches.

SourceGit will clone the main branch by default. If you wish to update to version 3.0 or otherwise the current release, branch, simply pull that branch into your local branch with right click -> "Merge into main".

Setting Up Lorekeeper

We need to install two more pieces of software before we can get our copy of Lorekeeper fully up and running.

Installing Composer

1. First, we will install Composer, which handles installation of PHP packages. Go here and select "Download".

2. Click the link for the Windows Installer, then run it.

3. Click to install for all users.

4. Leave developer mode unchecked. Click "Next".

5. XAMPP should be automatically selected as your command line version of PHP. If not, use the dropdown to select it. If prompted, also select the checkmark to add it to your path.

6. Click "Next" on this screen.

7. You will see a screen similar to this one, summarizing your options. Click "Install".

8. On this screen, click "Next".

9. Then, click "Finish"!

10. Reboot your computer. While Composer mentions that it won't always be necessary, rebooting our computer after installing Composer is the best way to prevent issues.

Installing Visual Studio Code

Visual Studio Code is the code editor we will use to edit our Lorekeeper files.

A Note for Advanced Users

You can install the VSCodium open source version, which comes with AI/Copilot features disabled by default, here. However, you may run into issues with using certain extensions due to Microsoft's licensing.

1. Go here to download it and press the big download button. (Fortunately, we can disable the recently added AI features.)

2. Run the newly downloaded file. You will be presented with the license agreement. Check the agree button, then click "Next".

3. Check all the boxes (with desktop icon checked depending on your preference) and click "Next".

4. Click "Install".

5. It will then install. Check the button to launch it, then click the "Finish" button when complete.

Disabling AI Features

Microsoft constantly changes how to disable AI features within Visual Studio Code. As a result, unfortunately we can not provide up-to-date instructions. Please use your favorite search engine to find the latest way to disable these features.

The Lorekeeper community does not encourage, promote, or endorse usage of AI tools.

Running Lorekeeper

1. Open up the File Explorer and navigate to where Lorekeeper is installed on your computer. This is likely to be C:/xampp/htdocs/lorekeeper if you've been following our guides.

2. Right click anywhere in the empty space (make sure you don't have a file/directory selected!) and click "Open With Code".

3. Behold! All of the files that make up your Lorekeeper. However, we need to install a few files before it will work properly. In the top bar, click "Terminal" and then "New Terminal".

4. Type in composer install. A lot of text will go flying by as composer installs the various chunks of code required for LK to run.

It may get stuck for a while on Generating optimized autoload files. Be patient! It will finish eventually.

It should look like this when done:

5. Next, we will create the .env file, which will define some variables that Lorekeeper needs to run. Right-click near the bottom of the file list and click "New File". Name this file .env.

6. The file should open by default (if not, double click it to open it). You will see a screen like this:

8. We're going to paste a lot of text here! Here is the contents to paste into this file:

APP_NAME=Lorekeeper
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

CONTACT_ADDRESS=
DEVIANTART_ACCOUNT=

LOG_CHANNEL=stack
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=lorekeeper
DB_USERNAME=root
DB_PASSWORD=

BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=

PUSHER_APP_ID=
PUSHER_APP_KEY=
PUSHER_APP_SECRET=
PUSHER_APP_CLUSTER=mt1

MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

9. Save the file. Now, go back to the terminal. We are going to run a few setup commands. Type in php artisan key:generate. You will see something like this:

10. Next, type in php artisan migrate. This will populate the database with all of the tables that Lorekeeper needs to function. You'll see a LOT of text start to fly by. It should look like this when completed:

Adding MySQL to your PATH Variable

If you run into an error when running php artisan migrate, you may need to add MySQL to your computer's PATH variable.

1. Open your start menu and search for "edit system environment variables".

   

2. Click "Environment Variables" in the pop-up.

3. Under "System Variables", selected "Path" and then "Edit..."

4. Click "New".

5. Type in the location of your MySQL bin folder. For example, if you followed our XAMPP guide, this will be located C:\xampp\mysql\bin. Click OK to save.

6. Restart Visual Studio Code as well as any other command prompts you have open for the changes to reflect.

11. Now for some Lorekeeper-specific commands. Run php artisan add-site-settings to populate the database with the site settings. It should look like this when completed:

12. Then run php artisan add-text-pages. This will add the default text pages for LK:

13. Next run php artisan copy-default-images. This will add the default images for various features on LK:

14. Finally, we will run the command php artisan setup-admin-user. This will create user #1, the default admin account. The email and details you give it do not need to be real, but make them something you'll remember easily.

• Proceed to create account with this information? (yes/no) Answer yes.
• Are you on a local/testing instance and not a live site? (yes/no) Answer yes.
• Would you like to mark your email address as verified and enter an alias now? (yes/no) Answer yes.

The important details to mark as yes have been highlighted in red.

15. Now, go to http://localhost in your browser. You can also access this by pressing the "Admin" button next to "Apache" in XAMPP.

Setup Complete

You have finished installing a local copy of Lorekeeper. You can login as the admin account you just set up, and begin trying out the different features.

When you are ready, you can move onto configuration or setting up a live website.