Tutorial: Installing Extensions

This tutorial explains how to install Extensions from the Extensions Category onto your copy of Lorekeeper.

It is recommended that you at least read Installing and Merging sections before attempting to install any extensions. Not scrutinizing merges can have devastating consequences for your site.

Software

The software used in this tutorial will mainly be:

• Sourcetree, which is recommended as a GUI (graphics user interface, as opposed to running lines of code) for Git (a repository).
• Visual Studio Code, abbreviated into VSC by most, which is a program used to edit code.
  • It is recommended above programs like Notepad++ for its utility, such as formatting and highlighting code and how it treats merging conflicts in Sourcetree/git.

You should probably install BOTH if you don't have any experience with web/coding and are new to this!

Installing

Installing is very fast and simple, and the actual installation itself only takes a few minutes.

1. Adding the Extension's Repository as a Remote.

We need to do this so you can install an extension's files into your local and site copies of lorekeeper.

From an Extension's wiki page, there is a link in the top right which leads to the corresponding git repository.

IMAGE: Screenshot of the Extension Link Location

At the repository, you'll want to copy the link.

IMAGE: The Git Repository

Then, you'll want to go to your Lorekeeper's repository in Sourcetree. Click the Gear on the top right to open settings. Then click Add to add a new remote-- this allows you to pull code from that project.

IMAGE: Adding an extension's repository to your lorekeeper Sourcetree.

As a note, this gives you access to ALL the extensions made by this person, not just the one you want. Which is fine!

2. "Pulling" the Extension into your local copy.

We are going to pull the extension's files. In Sourcetree, you'll want to click the Pull button on the top left. Then select the remote that you had just added and named. Hit the Refresh button, otherwise the extensions will not show up. Select your extension by its name.

IMAGE: Selecting an extension to pull.

For the Options, turn off Commit merged changes immediately. The other options are up to you, but I would recommend leaving them all off.

Hit Pull! If successful, Sourcetree will pull, and then you will have a blue number indicator around the Commit button.

3. Reviewing Changes

A commit is essentially saving the changes into a version of your repository. Before committing, you can click on File Status in your Sourcetree Workspace to view which files are being changed.

IMAGE: Looking at which files are being changed.

It is good practice to go through most if not all of your staged files to review the changes, but understandably this is difficult for those with no coding experience. Instead, what you can do is look at the file names. If a file is suspiciously unrelated to the extension you're pulling, you should look in to see what's changed. If code is only ADDED, then it's probably okay. If code is removed, you may want to ask what the removal of that code does.

For example, The submissions extension used in the screenshots adds items to be spent by the user on claims and submissions. It should change files related to submissions, claims, users, and items. It also includes an extension which adds raffle tickets to submissions as a reward, so it will be editing raffles.

I was not sure if it should be editing anything named PROMPTS, so I clicked on the app/Models/Prompt/PromptReward.php file to see what it had changed. The changes are only added code, adding something called 'Raffle', which seems safe, so that change is fine. I also did not know what the app/Services/Item/BoxService.php file was about having no experience with it, but on inspecting it I noticed that all of the added code also has the key word 'raffle' included somewhere, so they're intentional and related changes.

While going through files like this, I also noticed that it changed the file called config/lorekeeper/settings.php and config/lorekeeper/image_files.php to add code related to meta-image data. I didn't read anything about this on the wiki, so I asked merc and they explained their extensions are based off of their branch of lorekeeper which includes some extra functions and bug fixes. One of these is meta data. It's an intentional change, and does not interfere with base lorekeeper nor the submissions add-on, so it's safe. DO NOT BE AFRAID TO ASK QUESTIONS IF YOU SEE A SUSPICIOUS FILE!

For more information on identifying the functions and workings of Lorekeeper files, please see Troubleshooting below.

4a. Sourcetree Said you had Conflicts which needed to be resolved...

This is a common issue when you pull multiple extensions, or make changes before pulling an extension. This happens when an extension edits a piece of code which interferes with a previous change.

You will need to go through all of the conflicts and manually tell Sourcetree which ones are okay. Please see Merging below for how to accomplish this in more detail.

4b. "Commit" Changes to your local branch

If everything looks good to go (you did not get conflicts and none of the files are suspicious), click the Commit button on the bottom right. This will create a new commit on Sourcetree with your merge.

Then, click Push!

IMAGE: Commit and Push your changes.

You will be pushing to your website!

5. Extra Setup

Some add-ons have additional set up. Some will require you to add links to _nav or change settings. Others will require you to run a migration.

To run a migration, open Putty and navigate to your site folder: using this code

cd ~/site-name.com/www

Then run the migration:

php artisan migrate

It may as you yes/no, type yes.

Check your site very quickly to make sure it's still working, and that the new add-ons are doing what they need to be doing. If you have any issues, see Troubleshooting below.

Merging Conflicts

If you hit a conflict, you'll need to manually check all conflicts before being able to commit and push your changes.

It is EXTREMELY IMPORTANT that you take care when encountering conflicts!

IMAGE: the dreaded merging conflicts warning.

You'll need to go to File Status. When you go, you'll notice that there are various icons on your Staged Files List:

IMAGE: conflicts in your File Status.

Click the little "-" next to all files which have a ! triangle to indicate a conflict. This removes them from your staged files. (A staged file is a file which is set to be committed; unstaged is not yet set to be committed). Git will yell at you if you try to stage things that are already partially staged, so this is why we're doing that. Once your Staged files section is clear of conflicts, you'll want to

Troubleshooting

Troubleshooting can be frustrating, but your peers in discord can help so do not be afraid to ask questions.

Lorekeeper File Identification

First, I'd highly recommend browsing The Parts of the Process section of this tutorial. They explain the different types of files. The names of the file types generally fit the layout of the files in your lorekeeper.

IMAGE: The basic layout of files.

Within controllers, models, services, and views, you will find that files are organized loosely in the following ways:

• ADMIN: this folder holds all files related to the ADMIN side of things. For example, if you're looking for the files that deal with admins viewing and accepting submissions, you'll go here.
• ACCOUNT: folders labelled account generally deal with settings, profiles, notifications, bookmarks, etc.
• CHARACTERS: these deal with characters, creation of characters, editing of them, etc.
• FEATURES: this is the coding label for anything doing with Traits.
• BROWSE: These folders are generally for public pages that anyone, even logged out, can view. Also includes stuff for 'browsing' masterlists and indexes.
• HOME: This section generally has to do with a player's view of their own inventory, bank, queues, etc.
• WORLD: This section includes anything found in the Lorekeeper Encyclopedia (lists for all traits/items/species/etc).

This is not a comprehensive list of all folder labeling, but they give a good idea of the 'logic structure' of these folders. Everything tends to be labelled based on what it has to do with! Knowing how to navigate these folders can help pinpoint issues more quickly.

Finding an Issue

Any time you hit a 500 error on your site, you will want to 'pull the logs'. Using Filezilla or some other FTP client is the easiest way to do this. Navigate to the following folder:

/site-name.com/www/storage/logs

and find a file with a name formatted like laravel-yyyy-mm-dd such as laravel-2020-08-30 for example. The date should match today's date. Open it (with notepad, visual studio, whatever text editor, doesn't need to be complex) and you will see a mess of text. These are all your error logs. The top is the oldest, and the bottom are the most recent, so scroll all the way to the bottom. You will notice that they are formatted in a certain way:

[yyyy-mm-dd hh:mm:ss] type of ERROR: description of the error and files/lines related to that error going on for several long or short lines.

1. 0 A bunch of indiscernable laravel nonsense

1. 1 Which continues for like 50 of these lines

1. 3 Depending on how complex your problem is

1. 4 etc etc

The important part is the entire section from the [date] ending before the #0. That is your basic error code!

The error log will often talk about any problematic variables, missing information, or broken coding (demanding } or ;). It will also sometimes throw the location of a specific file in the format of (View: /home/username/site-name.com/www/folders folders folders/file.type:00 You can navigate to the offending file using this as a guide. If you're lucky, the code will have a colon at the end followed by a number-- this refers to a specific line in the code! If you open your file in Visual Code Studio, sometimes it can automatically pinpoint errors for you. Otherwise, if you don't know what you're doing, you should bring this information into the discord for help.

If you share that in the discord, it's way easier to help you with your issue. You should just fill this form out when asking for help in the help chats:

Where: [what page, what you did to encounter the bug]

Site: [a link to your site can be helpful]

Extensions: [what extensions you recently added that may be related]

Error Log: [the error in the log, copy pasted

Code: [If your error log talks about a specific line of code, please copy paste it between ``` - ``` or share it in a pastebin.]

Reversing an Entire Extension Installation

To undo an installation, go to the commit in your history. Right click, then select "Reverse Commit". Click Yes when Sourcetree asks if you'd like to reverse your commit. Then Push to your website, and be sure to check Force Push in order to override the current site's files. If Force Push is not available, you may need to turn it on in your settings.

IMAGE: Enabling Force Push. IMAGE: Force Pushing a reversed commit.

Force push is necessary as without it, it may pretend to have updated your files but not performed the update due to your sourcetree being "behind" the site. You should check now to be sure the changes actually went through.

Additionally, if you had to run any migrations in Putty, you can undo the most recent migration by running this code:

cd ~/site-name.com/www

php artisan migrate:rollback

This will undo the most recent migration. Alternately, you can go into mySQL (or your database) and manually delete the columns/tables/etc that were added (do not do this unless you KNOW which ones for certain).