Tutorial: Installing Extensions

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

Please read Installing and Merging sections before attempting to install any extensions. Not scrutinizing merges can have devastating consequences for your site. It suggested to have a Local instance set up to test your extensions before pushing them to your live 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 can be very fast and simple, but it is important to follow each step carefully and fully before proceeding. Please note that installing multiple extensions can be significantly more complex. Extensions should always be installed one at a time and fully tested before adding additional extensions.

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 Added + Removed (so, changed) it's prooobably okay, just check if it's relevant to the extension. If code is removed entirely, 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.

If you find a change you DO NOT want (small example, if someone adds an extra line that doesn't need to be there) you can highlight the line on Sourcetree and click the Discard Line button. This will remove the change utterly and completely and you don't even have to commit it. If a line is not highlighted, the Discard Line button changes to the Discard Hunk button, which you can use to discard the whole section displayed. Or, you can right click on a file and discard the entire file's changes right then and there. Only discard changes if you're sure you don't want them though!

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 Conflicts 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.

5. Local Setup

Note - choosing to not test locally can result in much more challenging problems to solve!

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 or other commands. This information can be found in the documentation for the extension.

To run a migration, open command and navigate to your site folder with the below code.

cd <directory>

Run any codes required in the documentation.

6. Testing

It is important to fully test each extension you install. Launch your local site. To manually test your new extension try out each function of the site that the extension impacts. For example, if you install the advent calendar extension you should test out making an advent calendar, and test out receiving items from it. Thorough local testing can help prevent problems on your live site!

If you have any issues, see Troubleshooting below.

7. Push to Site

Once you have fully tested your new extension on local you can push your changes to your live site! Return to SourceTree and hit the push button!

Do not push to your site if you have any errors on your local instance, as this will create the same errors on your live site!

IMAGE: Commit and Push your changes.

8. Complete Set Up

If the extension you installed requires additional commands you should now run them in Putty.

Open Putty and navigate to your site folder: using this code

cd ~/site-name.com/www

Then enter any commands indicated in the extension’s documentation. Once you have run all required commands your extension should be live on your site!

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 Review your Changes. It is even more vital to look at any code that is removed without being replaced! Please read the instructions for reviewing your changes and follow them religiously. It is definitely better safe than sorry, here!

Then, it's time to crack your knuckles and set to reviewing the Unstaged Files. Select an unstaged file and you should be able to view the changes on the right. If you see any of the following types of code:

<<<<<<< HEAD
=======
>>>>>>> 2281gaoiwe3hgoi4hg2049209b8aba7600

You will want to open that file in Visual Code Studio! When Git encounters a conflict, it puts in these brackets to keep track of both the current code, and the conflicted code. VSC can read these changes and show them to you in a more digestible way:

IMAGE: Sourcetree trying its best to show you a conflict. IMAGE: VSC doing a better job with the same file.

If you try to resolve this purely through Sourcetree alone, a lot of times it's not intelligent enough to remove the <<< >>>> HEAD === stuff on its own, and also doesn't actually resolve the conflict very well. Oops. Looking at this specific code through Sourcetree, it's confused about how to merge this code. You do NOT want lines of code to needlessly repeat (this can actually cause 500 errors). This specific error is caused because RAFFLES and AWARDS changed the same sections. What you'll want to do is merge them in a way that preserves both. Compare the code to see what is similar and what is different. Sometimes, there will be silly empty incoming/current changes-- this mostly just means Git did a Bad Job Interpreting what happened here, and you can mostly just accept whichever change is not empty.

IMAGE: Using VSC to compare code. GIF: Very quick example of how to edit the conflict in VSC.

Once you've used VSC to merge the code manually, the >>> <<<=== HEAD stuff should all be gone, and you should be left with some nice and neat code. NOTE: Be sure to keep an eye on brackets (that is, (), [], and {} to be sure that your edits do not destroy the hierarchy of the brackets. Every open bracket (left bracket) needs a closing bracket (right bracket) or the code will break. ALSO be sure that you are preserving ; (semicolons) where they need to be (check the surrounding code if they have ; at the end of each line) and for the presence or absence of commas. If you're not sure, you can reference other chunks of code within the same file. Luckily, having these issues will normally cause 500 logs which tell you which file and which line specifically are breaking, so they're easier to troubleshoot if you overlook them (see Finding an Issue).

IMAGE: Example of paying attention to semicolons and commas.

When you go back into Sourcetree, you'll notice that the file no longer has HEAD in it-- it will have changed its view to be more like a normal change, with Red lines marking deletions and Green lines marking additions. You should be able to stage the file now with no consequences (push the '+' to the right of the file name).

Scrutinize your conflicts mercilessly! When you've gone through every single conflict and your Unstaged files section is empty, you can finally commit and test locally.

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.

#0 A bunch of indiscernable laravel nonsense
#1 Which continues for like 50 of these lines
#3 Depending on how complex your problem is
#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 by underlining them in jagged red lines. 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

** NOTE: YOU CAN ONLY DO THIS IF YOUR MOST RECENT ACTION IS INSTALLING THE EXTENSION. IF YOU HAVE DONE ANYTHING ELSE SINCE THEN, DO NOT ATTEMPT TO REVERSE THE INSTALLATION UNLESS YOU KNOW EXACTLY WHAT YOU'RE DOING. YOU ARE LIABLE TO BREAK YOUR SITE AND/OR PORTIONS OF ITS FUNCTIONALITY. **

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).