Difference between revisions of "Tutorial: Setting Up"

From Lorekeeper Wiki
Jump to navigation Jump to search
Tag: 2017 source edit
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Visual Guides =
+
==Visual Guides==
 
Some Lorekeeper users have written extensive guides on setting up:
 
Some Lorekeeper users have written extensive guides on setting up:
  
Juni's Dreamhost visual setup guide: <nowiki>https://docs.google.com/document/d/1mpb1KJIKN_yi8aXOs6AwfRrf5D0XwvQxbvmPa3t31xg/edit#heading=h.4dhzdpddx1gk</nowiki>
+
*[https://docs.google.com/document/d/1mpb1KJIKN_yi8aXOs6AwfRrf5D0XwvQxbvmPa3t31xg/edit#heading=h.4dhzdpddx1gk Juni's Dreamhost visual setup guide]
 +
*[https://docs.google.com/document/d/1deGtEdt9Dka3OpIHE7esEAfmrkvdRejHGOQxFu1TWP8 wych(witch)'s DigitalOcean visual setup guide]
  
wych(witch)'s DigitalOcean visual setup guide: <nowiki>https://docs.google.com/document/d/1deGtEdt9Dka3OpIHE7esEAfmrkvdRejHGOQxFu1TWP8</nowiki>
+
It's recommended to use either of these guides as they're highly detailed and contain more screenshots!
 
 
Recommended to use either of these guides as they're highly detailed and contain more screenshots!
 
  
 
'''What is the difference?'''
 
'''What is the difference?'''
Line 14: Line 13:
 
The information below is the same as detailed in Juni's guide, but more general/doesn't contain info about setting up on a shared server/configuring passwordless login.
 
The information below is the same as detailed in Juni's guide, but more general/doesn't contain info about setting up on a shared server/configuring passwordless login.
  
= Requirements =
+
===Setting up Locally===
 +
There is also a community tutorial on setting up Lorekeeper locally:
 +
 
 +
*[[Tutorial: Local Host]]
 +
 
 +
This has superseded the information in this guide relating to local set-up in the interest of clarity. '''Having a local/testing environment is a prerequisite for most support'''.
 +
 
 +
However, it's also an option if you want to try out or experiment with Lorekeeper, e.g. before committing to hosting!
 +
 
 +
==Requirements==
 
Requirements for a web host (assuming it's running on some variant of Unix):
 
Requirements for a web host (assuming it's running on some variant of Unix):
  
* PHP 7.2
+
*PHP 7.4
* MySQL
+
**Note that you need PHP 7.4 specifically; later versions have no guarantee of working.
* SSH access
+
*MySQL (or equivalent)
 +
*SSH access
  
If you're not familiar with any of these and don't want to spend too much time shopping around hosts, I personally recommend going with DreamHost's VPS (the cheapest plan will do) as they have everything necessary (the demo site is hosted by them) and their own written instructions for some of the steps in the setup, which I have linked below.
+
If you're not familiar with any of these and don't want to spend too much time shopping around hosts, I personally recommend going with [https://www.dreamhost.com/ DreamHost]'s VPS (the cheapest plan will do) as they have everything necessary (the [http://lorekeeper.me/ demo site] is hosted by them) and their own written instructions for some of the steps in the setup, which I have linked below.
  
 
Additional software requirements:
 
Additional software requirements:
  
* PuTTY (if using Windows) / a program that can be used to SSH into your server
+
*[https://www.putty.org/ PuTTY] (if using Windows) / a program that can be used to SSH into your server
* A Git client (e.g. Sourcetree)
+
*A Git client (e.g. [https://www.sourcetreeapp.com/ Sourcetree], recommended if you are new to git, or preferred client if you already have one)
* A text editor (Notepad works, but I recommend something more featured e.g. Visual Studio Code, Notepad++)
+
**You '''must use git, no exceptions'''. This is required to be able to obtain updates, etc.
* A command line program (for your computer - on windows, this is Command Prompt)
+
*A text editor, preferably one designed for navigating and editing code
 +
**[https://code.visualstudio.com/ Visual Studio Code] is recommended!
 +
*An FTP client
 +
**On Windows, [https://winscp.net/eng/index.php WinSCP] is recommended (it can import settings from PuTTY as well)
 +
*A command line program (for your computer - on windows, this is Command Prompt)
  
= Preface =
+
==Preface==
 
Setting up your own copy of Lorekeeper consists of 3 main steps:
 
Setting up your own copy of Lorekeeper consists of 3 main steps:
  
# Uploading a copy to your web host
+
#Uploading a copy to your web host
# Setting up the database/admin account configuration
+
#Setting up the database/admin account configuration
# Site configuration/adding your ARPG data/modifying the source code
+
#Site configuration/adding your ARPG data/modifying the source code
  
 
If you have a personal favourite method of setting up your workflow, I would strongly recommend going with what you're comfortable with! Jump ahead to step 2 as there are a few commands you have to run from the command line.
 
If you have a personal favourite method of setting up your workflow, I would strongly recommend going with what you're comfortable with! Jump ahead to step 2 as there are a few commands you have to run from the command line.
Line 41: Line 54:
 
Otherwise, for this tutorial, I'll assume that you have never touched Git and worked on the command line before, and will run through the steps I go through to get this up and working, with my usual workflow. Refer to the basic version of the tutorial to get it uploaded with less fuss, but less convenience working with the source code.
 
Otherwise, for this tutorial, I'll assume that you have never touched Git and worked on the command line before, and will run through the steps I go through to get this up and working, with my usual workflow. Refer to the basic version of the tutorial to get it uploaded with less fuss, but less convenience working with the source code.
  
= Uploading =
+
==Uploading==
We're going to set this up so that we can use Git to manage changes to the site. The setup is based on this article (with a few modifications + expanding on the comments).
+
We're going to set this up so that we can use Git to manage changes to the site. The setup is based on [http://joemaller.com/990/a-web-focused-git-workflow/ this article] (with a few modifications + expanding on the comments).
  
== Obtaining Local and Server Copies ==
+
===Obtaining Local and Server Copies===
First, we want to make sure we have the software we need. For Windows PCs, download PuTTY from here and install/set it up (click here for instructions).
+
First, we want to make sure we have the software we need. For Windows PCs, download PuTTY from [https://www.putty.org/ here] and install/set it up (click [https://help.dreamhost.com/hc/en-us/articles/215464538-How-do-I-configure-PuTTY- here] for instructions).
  
 
Next, we need hosting and a domain name. I'll be using Dreamhost in the examples of this tutorial for hosting.
 
Next, we need hosting and a domain name. I'll be using Dreamhost in the examples of this tutorial for hosting.
Line 53: Line 66:
 
Obtain a copy of Lorekeeper. The recommended way to do this is to git clone it on your computer - there are various ways of doing this, but the simplest way is probably to clone it from your Git client. This will also initialise it as a Git repository on your computer. Now, you have a copy of Lorekeeper on your computer that you can use for working. I'll call this your '''local copy''', and the one on your server the '''server copy''' (or live site).
 
Obtain a copy of Lorekeeper. The recommended way to do this is to git clone it on your computer - there are various ways of doing this, but the simplest way is probably to clone it from your Git client. This will also initialise it as a Git repository on your computer. Now, you have a copy of Lorekeeper on your computer that you can use for working. I'll call this your '''local copy''', and the one on your server the '''server copy''' (or live site).
  
We're going to get the code onto the server. Using your SSH client (PuTTY on Windows/Terminal on Mac) SSH into your server - here are Dreamhost's very detailed instructions on how to do that.
+
We're going to get the code onto the server. Using your SSH client (PuTTY on Windows/Terminal on Mac) SSH into your server - [https://help.dreamhost.com/hc/en-us/articles/216041267 here] are Dreamhost's very detailed instructions on how to do that.
  
 
From here on, you can enter the commands almost exactly as they are.
 
From here on, you can enter the commands almost exactly as they are.
{| class="wikitable"
+
 
|
 
|-
 
|
 
|-
 
|Creating and initialising the directories on the server.
 
|}
 
 
Navigate to the directory we're putting the files in.
 
Navigate to the directory we're putting the files in.
  <code>cd ~</code>
+
  <pre>cd ~</pre>
 
Make a directory for your site - name it whatever you want. In this example I'll use "site-name.com", so replace that with your site name.
 
Make a directory for your site - name it whatever you want. In this example I'll use "site-name.com", so replace that with your site name.
  <code>mkdir site-name.com
+
  <pre>mkdir site-name.com
cd site-name.com</code>
+
cd site-name.com</pre>
Make a directory called <code>www</code>, go in and git init it.
+
Make a directory called www, go in, and git init it.
  <code>mkdir www
+
  <pre>mkdir www
cd www
+
cd www
git init</code>
+
git init</pre>
Go back out and make a second directory named <code>site_hub.git</code> and init it as a bare repository.
+
Go back out, make a second directory named site_hub.git, and init it as a bare repository.
<code>cd ..
+
<pre>cd ..
mkdir site_hub.git
+
mkdir site_hub.git
cd site_hub.git
+
cd site_hub.git
git --bare init</code>
+
git --bare init</pre>
Go to your Git client (e.g. Sourcetree as suggested above), select your folder containing Lorekeeper's code and add site_hub.git as a remote. The address is similar to your SSH address but points directly to the folder, something like <code><nowiki>ssh://username@host.com/~/site-name.com/site_hub.git</nowiki></code>.
+
Go to your Git client (e.g. Sourcetree as suggested above), select your folder containing Lorekeeper's code and add site_hub.git as a remote. The address is similar to your SSH address but points directly to the folder, something like <pre><nowiki>ssh://username@host.com/~/site-name.com/site_hub.git</nowiki></pre>If successful, push the code to the remote. In Sourcetree, right click on the remote, choose to push, select the main branch and click OK.
  
If successful, push the code to the remote. In Sourcetree, right click on the remote, choose to push, select the master branch and click OK.
 
{| class="wikitable"
 
|
 
|-
 
|
 
|-
 
|Adding the remote on the server.
 
|}
 
{| class="wikitable"
 
|
 
|-
 
|
 
|-
 
|Adding the remote in Sourcetree.
 
|}
 
 
Back in the SSH client, we'll add site_hub.git as a remote for www.
 
Back in the SSH client, we'll add site_hub.git as a remote for www.
  <code>cd ../www
+
  <pre>cd ../www
git remote add hub ../site_hub.git</code>
+
git remote add hub ../site_hub.git</pre>
At this point if you enter <code>git remote show hub</code>, you should see something like
+
At this point if you enter <pre>git remote show hub</pre>, you should see something like
  <code>* remote hub
+
  <pre>* remote hub
   URL: /home/your_username/site-name.com/site_hub.git</code>
+
   URL: /home/your_username/site-name.com/site_hub.git</pre>Run a git pull.<pre>git pull hub main</pre>
{| class="wikitable"
+
Wait for it to finish running, and if it looks like nothing went wrong, enter <pre>ls</pre> and see that there are files inside the directory.
|
 
|-
 
|
 
|-
 
|Running git pull.
 
|}
 
Run a git pull.
 
<code>git pull hub master</code>
 
Wait for it to finish running, and if it looks like nothing went wrong, enter <code>ls</code> and see that there are files inside the directory.
 
  
== Git Hooks ==
+
===Git Hooks===
{| class="wikitable"
 
|
 
|-
 
|
 
|-
 
|Creating a hook.
 
|}
 
 
If everything looks good, we'll set up git hooks so that updating the site is as easy as pushing a button.
 
If everything looks good, we'll set up git hooks so that updating the site is as easy as pushing a button.
  
 
Continue by entering
 
Continue by entering
  <code>cd .git/hooks
+
  <pre>cd .git/hooks
nano post-commit</code>
+
nano post-commit</pre>
 
This will bring up a blank text editor. Enter the following text:
 
This will bring up a blank text editor. Enter the following text:
  <code>#!/bin/sh
+
  <pre>#!/bin/sh
 
   
 
   
 
  echo
 
  echo
Line 131: Line 107:
 
  echo
 
  echo
 
   
 
   
  git push hub</code>
+
  git push hub</pre>
 
 
  
 
To save the file, enter in order: Ctrl + X, y, enter.
 
To save the file, enter in order: Ctrl + X, y, enter.
  
 
Then, we'll change the permissions on the file:
 
Then, we'll change the permissions on the file:
  <code>chmod +x post-commit</code>
+
  <pre>chmod +x post-commit</pre>
 
We'll also add a hook in site_hub.git.
 
We'll also add a hook in site_hub.git.
  <code>cd ../../../site_hub.git/hooks
+
  <pre>cd ../../../site_hub.git/hooks
  nano post-update</code>
+
  nano post-update</pre>
 
The contents of this file (note the directory name you have to edit below!!):
 
The contents of this file (note the directory name you have to edit below!!):
  <code>#!/bin/sh
+
  <pre>#!/bin/sh
 
   
 
   
 
  echo
 
  echo
Line 150: Line 125:
 
  cd $HOME/site-name.com/www || exit
 
  cd $HOME/site-name.com/www || exit
 
  unset GIT_DIR
 
  unset GIT_DIR
  git pull hub master
+
  git pull hub main
 
   
 
   
  exec git-update-server-info</code>
+
  exec git-update-server-info</pre>
 
 
  
 
Once again: Ctrl + X, y, enter.
 
Once again: Ctrl + X, y, enter.
  
 
And again, we'll change the permissions on the file:
 
And again, we'll change the permissions on the file:
  <code>chmod +x post-update</code>
+
  <pre>chmod +x post-update</pre>
You can now test the hooks by modifying something harmless on your local copy (such as a comment) and commit/pushing the change to the server.
+
You can now test the hooks by modifying something harmless on your local copy (such as a comment, or adding small text file) and commit/pushing the change to the server.
  
 
If set up correctly, the output log should display the message you wrote in post-update and show that the file was updated without errors.
 
If set up correctly, the output log should display the message you wrote in post-update and show that the file was updated without errors.
  
For a small but important tweak, we'll change the origin of our repository to point to the new site. This is demonstrated in Sourcetree, but should not be too much different in other clients.
+
For a small but important tweak, we'll change the origin of our repository to point to the new site.
  
# Checkout the site's master branch.
+
#Checkout the site's main branch.
# Rename the old origin branch.
+
#Rename the old origin branch.
# Change the site's master branch to origin.
+
#Change the site's main branch to origin.
 
 
 
 
  
 
In the future, you (and other users who have access to the repository) can simply push new changes to the code through your Git client at the click of a button, which also keeps track of files that you've added and/or modified, and contains a log of who made what changes to the code. Hooray!
 
In the future, you (and other users who have access to the repository) can simply push new changes to the code through your Git client at the click of a button, which also keeps track of files that you've added and/or modified, and contains a log of who made what changes to the code. Hooray!
  
= Setting Up =
+
==Setting Up==
  
== Web Directory ==
+
===Web Directory===
 
Update your domain to point to the www/public folder.
 
Update your domain to point to the www/public folder.
  
 
For DreamHost users, this is under Manage Domains > Edit > Web directory. The page may take a few hours to update, and display an error if you have not completely finished the setup yet (this is normal).
 
For DreamHost users, this is under Manage Domains > Edit > Web directory. The page may take a few hours to update, and display an error if you have not completely finished the setup yet (this is normal).
{| class="wikitable"
+
===Install Composer===
|
+
Packages for the project are installed through Composer.
|-
 
|
 
|-
 
|Sample web directory.
 
|}
 
  
== Install Composer ==
+
Instructions for installing Composer on your server are [https://help.dreamhost.com/hc/en-us/articles/214899037 here]. I recommend following the global instructions. If you follow the local setup, place composer.phar in the www directory.
Packages for the project are installed through Composer. You'll want to have it installed both on the server and on your computer.
 
  
Instructions for installing Composer on your server are here.
+
Additionally, if you're using DreamHost, you will want to change the default PHP version for convenience. See [https://help.dreamhost.com/hc/en-us/articles/214202148 here] for instructions.
  
Instructions for installing Composer on your computer are here.
+
===Packages and Database Setup===
 
+
In your SSH client, navigate to the www folder and run composer install.
I recommend following the global instructions. If you follow the local setup, place composer.phar in the www directory.
+
<pre>cd ~/site-name.com/www
 +
composer install</pre>
 +
Let it finish running. After that, we'll set up the database.
  
Additionally, if you're using DreamHost, you will want to change the default PHP version for convenience. See here for instructions.
+
If you're not on DreamHost:
 
 
Note: At the time of coding, I was using PHP 7.2; when changing the PHP version make sure to use either 7.2 or 7.3. (i.e. replace all instances of <code>php74</code> with <code>php72</code> or <code>php73</code>)
 
 
 
== Packages and Database Setup ==
 
In your SSH client, navigate to the www folder and run composer install. (Do this also on your own computer, but navigate to the appropriate directory instead)
 
<code>cd ~/site-name.com/www
 
composer install</code>
 
Let it finish running. After that, we'll set up the database.
 
{| class="wikitable"
 
|
 
|-
 
|
 
|-
 
|Creating a DreamHost database in the control panel.
 
|}
 
If you're not on DreamHost or are setting up your local copy:
 
  
 
This is easiest through phpMyAdmin, so navigate to your site's phpMyAdmin in your browser.
 
This is easiest through phpMyAdmin, so navigate to your site's phpMyAdmin in your browser.
Line 218: Line 170:
 
Click on "Databases" in the top bar, and add a database - it can be called anything you like.
 
Click on "Databases" in the top bar, and add a database - it can be called anything you like.
  
If you're on DreamHost, go to the control panel to set up a database (see image on right). Be sure to choose names and a password that cannot be easily guessed and note them down! You will need the '''database name''', '''database user''' (the New Username field) and '''database user password''' (the New Password field) later. The '''hostname''' can be used to access PHPMyAdmin - note this down as well.
+
If you're on DreamHost, go to the control panel to set up a database. Be sure to choose names and a password that cannot be easily guessed and note them down! You will need the '''database name''', '''database user''' (the New Username field) and '''database user password''' (the New Password field) later. The '''hostname''' can be used to access PHPMyAdmin - note this down as well.
  
== API Keys ==
+
===API Keys===
Now, we need to get access to services that will allow us to send e-mails (for registration/resetting passwords) and connect to deviantART (for verifying accounts).
+
Now, we need to get access to services that will allow us to send e-mails (for registration/resetting passwords) and connect to various social media, etc. platforms (for verifying accounts).
  
For a small site with little traffic, I'd suggest SendGrid (100 mails a day on their free plan), though you can use any service that you like.
+
For a small site with little traffic, I'd suggest [https://sendgrid.com/ SendGrid] (100 mails a day on their free plan), though you can use any service that you like.
  
 +
====SendGrid Setup====
 
If you're using Sendgrid, after you've created your account, go to API Keys under Settings in the Control Panel and create a new key. Note down the generated '''SendGrid API key''' as we'll need it later. Keep this a secret!
 
If you're using Sendgrid, after you've created your account, go to API Keys under Settings in the Control Panel and create a new key. Note down the generated '''SendGrid API key''' as we'll need it later. Keep this a secret!
  
On deviantART, while logged in, go to the developer area.
+
Note that you will need to verify your domain. See [https://docs.sendgrid.com/for-developers/sending-email/sender-identity here] for more information.
  
Click on Register Your Application.
+
====Social Media Platforms====
 +
As of [[Updating: to 2.0.0|2.0.0]], there are several options for platforms to use for account linking/verification. See [[:Category:Social Media Authentication|Category:Social Media Authentication]] for instructions for supported sites. Note that you will also need to enable these via config file later. Note that you must set up and enable '''at least one''' of these platforms for use for auth.
  
Give your application a name as you would a deviation, and under both <code>OAuth2 Redirect URI Whitelist (Required)</code> and <code>Original URLs Whitelist</code>, put your site's URL (e.g. <nowiki>http://site-name.com</nowiki>). Click save.
+
===.env===
 +
Now, let's use that information. The site requires a file named .env to be placed in the root directory (in www). Create this file locally, with the following contents/filling out the fields as noted (avoid using spaces in names):
  
This will add an application under Un-Published Applications on the developer page - you don't need to publish the application to use it.
+
<pre>
 +
APP_NAME=site_name_with_no_spaces
 +
APP_ENV=production
 +
APP_KEY=
 +
APP_DEBUG=false
 +
APP_URL=<nowiki>http://site-name.com</nowiki>
  
Note down the '''deviantART client_id''' and '''deviantART client_secret'''. We'll use these later, and again, keep the secret a secret!
+
CONTACT_ADDRESS=your_contact_address@site-name.com
 +
DEVIANTART_ACCOUNT=your-dA-group-account-username
 +
 +
LOG_CHANNEL=stack
 +
DB_CONNECTION=mysql
 +
DB_HOST=your_database_hostname
 +
DB_PORT=3306
 +
DB_DATABASE=your_server_database_name
 +
DB_USERNAME=your_server_database_user_name
 +
DB_PASSWORD=your_server_database_user_password
  
I recommend creating a second application for use with your local copy rather than using the same application. In this application, instead of your site URL, add localhost (e.g. I use <nowiki>http://127.0.0.1</nowiki>).
+
BROADCAST_DRIVER=log
 +
CACHE_DRIVER=file
 +
QUEUE_CONNECTION=sync
 +
SESSION_DRIVER=file
 +
SESSION_LIFETIME=120
  
== .env ==
+
REDIS_HOST=127.0.0.1
Now, let's use that information.
+
REDIS_PASSWORD=null
 +
REDIS_PORT=6379
  
The site requires a file named .env to be placed in the root directory of your site (in the www directory). We'll do this in both the local copy and the server copy, but with a few differences.
+
MAIL_DRIVER=smtp
 
+
MAIL_HOST=smtp.sendgrid.net
Create a file both locally and on the server that contains the following, filling out the fields as noted (avoid using spaces in names):
+
MAIL_PORT=587
<code>APP_NAME=site_name_with_no_spaces
+
MAIL_USERNAME=apikey
APP_ENV=
+
MAIL_PASSWORD=your_sendgrid_api_key
APP_KEY=
+
MAIL_FROM_ADDRESS=noreply@site-name.com
APP_DEBUG=
+
MAIL_FROM_NAME=mail_sender_name
APP_URL=
 
 
CONTACT_ADDRESS=your_contact_address@site-name.com
 
DEVIANTART_ACCOUNT=your-dA-group-account-username
 
 
LOG_CHANNEL=stack
 
 
DB_CONNECTION=mysql
 
DB_HOST=
 
DB_PORT=
 
DB_DATABASE=
 
DB_USERNAME=
 
DB_PASSWORD=
 
 
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.sendgrid.net
 
MAIL_PORT=587
 
MAIL_USERNAME=apikey
 
MAIL_PASSWORD=your_sendgrid_api_key
 
MAIL_FROM_ADDRESS=noreply@site-name.com
 
MAIL_FROM_NAME=mail_sender_name
 
 
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}"
 
 
DEVIANTART_CLIENT_ID=your_deviantart_client_id
 
DEVIANTART_CLIENT_SECRET=your_deviantart_secret
 
DEVIANTART_CALLBACK_URL=/</code>
 
  
 +
AWS_ACCESS_KEY_ID=
 +
AWS_SECRET_ACCESS_KEY=
 +
AWS_DEFAULT_REGION=
 +
AWS_BUCKET=
  
Leave the APP_KEY blank, as it will be generated in a later step.
+
PUSHER_APP_ID=
{| class="wikitable"
+
PUSHER_APP_KEY=
|
+
PUSHER_APP_SECRET=
|-
+
PUSHER_APP_CLUSTER=
|
+
MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
|-
+
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"
|Comparison of local (left) and server (right) .env.
+
</pre>
|}
 
On the '''local version''', find and fill out the following lines as such (if you created an extra app for testing on deviantART, change the dA client ID and secret to that):
 
<code>APP_ENV=local
 
APP_DEBUG=true
 
APP_URL=<nowiki>http://localhost</nowiki>
 
 
DB_HOST=127.0.0.1
 
DB_PORT=3306
 
DB_DATABASE=your_local_database_name
 
DB_USERNAME=root
 
DB_PASSWORD=</code>
 
  
 +
Leave the APP_KEY blank, as it will be generated in a later step. Also make sure to add information for the platform(s) used for auth to the end as in the platform-specific instructions!
  
(Note that in the image to the right, Mailtrap.io is being used for local emails and the CONTACT_ADDRESS and DEVIANTART_ACCOUNT options are missing, but should be required.)
+
Now, use an FTP client ([https://winscp.net/eng/index.php WinSCP] if following the recommendations) to upload this file to the www directory of your site. '''Note that this is the only file that should be added or modified this way; all other files <u>must</u> be modified locally and pushed to the server with git.'''
  
On the '''server version''', find and fill out the following lines as such:
+
===Command Line Setup===
<code>APP_ENV=production
 
APP_DEBUG=false
 
APP_URL=<nowiki>http://site-name.com</nowiki>
 
 
DB_HOST=your_database_hostname
 
DB_PORT=3306
 
DB_DATABASE=your_server_database_name
 
DB_USERNAME=your_server_database_user_name
 
DB_PASSWORD=your_server_database_user_password</code>
 
 
 
== Command Line Setup ==
 
 
Moving on to command line setup - now that we have the files in place, we're going to create the database tables, insert some basic required data, and get the crons (scheduled scripts; primarily for scheduled news posts) working.
 
Moving on to command line setup - now that we have the files in place, we're going to create the database tables, insert some basic required data, and get the crons (scheduled scripts; primarily for scheduled news posts) working.
  
On both local and on the server, run the following, letting each complete before the next one:
+
Run the following, letting each complete before the next one:
  <code>php artisan key:generate  
+
  <pre>php artisan key:generate  
php artisan migrate</code>
+
php artisan migrate</pre>
 
 
  
 
This will generate the app key (used for encryption) and create the database tables.
 
This will generate the app key (used for encryption) and create the database tables.
  
 
Run the following commands afterwards:
 
Run the following commands afterwards:
  <code>php artisan add-site-settings
+
  <pre>php artisan add-site-settings
php artisan add-text-pages
+
php artisan add-text-pages
php artisan copy-default-images</code>
+
php artisan copy-default-images</pre>
 
Then, we'll set up the admin user:
 
Then, we'll set up the admin user:
  <code>php artisan setup-admin-user</code>
+
  <pre>php artisan setup-admin-user</pre>
 
 
  
 
This will prompt you for the creation of the admin account, which will have access to all site data. On the live site, I would recommend using this as a purely administrative account and not the site owner's personal account. You can run this command again to change the email address and password of the account.
 
This will prompt you for the creation of the admin account, which will have access to all site data. On the live site, I would recommend using this as a purely administrative account and not the site owner's personal account. You can run this command again to change the email address and password of the account.
Line 354: Line 261:
 
At this point, you should be able to log into the site with the admin account.
 
At this point, you should be able to log into the site with the admin account.
  
== Cron Jobs ==
+
===Cron Jobs===
 
Finally, we'll set up the crons so we can make use of scheduling.
 
Finally, we'll set up the crons so we can make use of scheduling.
  
 
'''For non-DreamHost users:'''
 
'''For non-DreamHost users:'''
  
Refer to this article for how to edit the crontab file.
+
Refer to [https://www.lifewire.com/crontab-linux-command-4095300 this article] for how to edit the crontab file.
  
 
Add the following line, editing the directory name as necessary:
 
Add the following line, editing the directory name as necessary:
  <code>* * * * * cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1</code>
+
  <pre>* * * * * cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1</pre>
 
'''If you are using DreamHost:'''
 
'''If you are using DreamHost:'''
  
Line 368: Line 275:
  
 
Select the shell user, enter a title (not important; you can set this to your site name for easy identification), and under command to run, add:
 
Select the shell user, enter a title (not important; you can set this to your site name for easy identification), and under command to run, add:
  <code>cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1</code>
+
  <pre>cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1</pre>
 
 
  
 
Then choose the following options:
 
Then choose the following options:
Line 381: Line 287:
 
If you can view the site from the URL - congratulations, you've set up the site successfully!
 
If you can view the site from the URL - congratulations, you've set up the site successfully!
  
= Site Configuration =
+
===Site Configuration===
 
Before we start adding data, let's edit the config files in the code, making use of Git to send your updates to the server.
 
Before we start adding data, let's edit the config files in the code, making use of Git to send your updates to the server.
  
== Config Files ==
+
===Config Files===
In your local copy, open up config/app.php in your text editor of choice. The code is commented in detail, so you can read and modify the config as you need. Most settings do not need to be touched since you wrote them in .env, but you may want to edit the '''timezone''' to match the clock your community goes by.
+
In your local copy, open up config/app.php in your text editor of choice. The code is commented in detail, so you can read and modify the config as you need. Most settings do not need to be touched since you wrote them in .env, but you may want to edit the '''timezone''' to match the clock your community goes by. Note that this must be a PHP-supported time zone-- see [https://www.php.net/manual/en/timezones.php here] for a list.
  
Open up config/lorekeeper/settings.php. Similar to the above, you can read the comments and modify the config as required.
+
It's recommended at this point that you go through the following config files and modify them as desired:
  
In your Git client, choose the modified files, commit and push them (important: to your server, not Github!) with a helpful message. If the hooks have been set up correctly, you should see the effects on the live site after it's done. If not, and there were no errors, you may need to run <code>php artisan config:clear</code> on the server.
+
*config/lorekeeper/settings.php
 +
*config/lorekeeper/sites.php
 +
**This is where you enable the sites you set up for authentication use earlier!
 +
*config/lorekeeper/extensions.php
 +
*(If desired) config/lorekeeper/group_currency_form.php
 +
**See [[Galleries]] for more information
  
== Site Data ==
+
Similar to the above, you can read the comments and modify the config files as required.
 +
 
 +
In your Git client, choose the modified files, commit and push them (important: to your server, not GitHub!) with a helpful message. If the hooks have been set up correctly, you should see the effects on the live site after it's done. If not, and there were no errors, you may need to run <pre>php artisan config:clear</pre> on the server.
 +
 
 +
===Site Data===
 
Now we can start editing the site data. All changes on the live site will only stay on the live site, and all local changes will only remain local.
 
Now we can start editing the site data. All changes on the live site will only stay on the live site, and all local changes will only remain local.
  
 
Log in as the admin user and go to the admin panel (click the crown in the navigation bar). The first things you may want to edit are:
 
Log in as the admin user and go to the admin panel (click the crown in the navigation bar). The first things you may want to edit are:
  
* Site Settings
+
*Site Settings
* User Ranks (create moderator ranks)
+
*User Ranks (create moderator ranks)
* Pages (Terms of Service, Privacy Policy, About)
+
*Pages (Terms of Service, Privacy Policy, About)
* Site Images
+
*Site Images
  
 
You can, of course, dive right into editing the game data - I would recommend editing in the order:
 
You can, of course, dive right into editing the game data - I would recommend editing in the order:
  
* rarities
+
*rarities
* categories (trait categories, item categories, prompt categories, character categories)
+
*categories (trait categories, item categories, prompt categories, character categories)
* species, traits, items, currencies
+
*species, traits, items, currencies
* loot tables
+
*loot tables
* prompts, shops
+
*prompts, shops
  
 
Note that at least 1 character category is required to create any characters. More specific information about each type of data can be found on the respective wiki pages.
 
Note that at least 1 character category is required to create any characters. More specific information about each type of data can be found on the respective wiki pages.
  
= Troubleshooting =
+
==Troubleshooting==
'''Composer install error: The filter extension is missing.'''
+
Please open a ticket in the [https://discord.gg/U4JZfsu support Discord] for assistance!
 
+
[[Category:Documentation]]
You are probably using PHP 7.4 on the command line, change it to 7.2 or 7.3.
 
 
 
'''PHP Fatal error: Uncaught Error: Call to undefined function JsonSchema\Uri\filter_var() in …'''
 
 
 
Same as above, change to PHP 7.2 or 7.3.
 
 
 
'''500 Server Error trying to send emails'''
 
 
 
For people who registered accounts after April 6 2020, SendGrid requires the sender identity to be verified. See this article for details.
 

Latest revision as of 10:16, 21 November 2021

Visual Guides

Some Lorekeeper users have written extensive guides on setting up:

It's recommended to use either of these guides as they're highly detailed and contain more screenshots!

What is the difference?

These guides pertain to setting up on different webhosts. The outcome is the same, but cost of webhosting and involvement in setting up varies - please read through the guides and choose the type of webhosting that fits your needs/budget/time!

The information below is the same as detailed in Juni's guide, but more general/doesn't contain info about setting up on a shared server/configuring passwordless login.

Setting up Locally

There is also a community tutorial on setting up Lorekeeper locally:

This has superseded the information in this guide relating to local set-up in the interest of clarity. Having a local/testing environment is a prerequisite for most support.

However, it's also an option if you want to try out or experiment with Lorekeeper, e.g. before committing to hosting!

Requirements

Requirements for a web host (assuming it's running on some variant of Unix):

  • PHP 7.4
    • Note that you need PHP 7.4 specifically; later versions have no guarantee of working.
  • MySQL (or equivalent)
  • SSH access

If you're not familiar with any of these and don't want to spend too much time shopping around hosts, I personally recommend going with DreamHost's VPS (the cheapest plan will do) as they have everything necessary (the demo site is hosted by them) and their own written instructions for some of the steps in the setup, which I have linked below.

Additional software requirements:

  • PuTTY (if using Windows) / a program that can be used to SSH into your server
  • A Git client (e.g. Sourcetree, recommended if you are new to git, or preferred client if you already have one)
    • You must use git, no exceptions. This is required to be able to obtain updates, etc.
  • A text editor, preferably one designed for navigating and editing code
  • An FTP client
    • On Windows, WinSCP is recommended (it can import settings from PuTTY as well)
  • A command line program (for your computer - on windows, this is Command Prompt)

Preface

Setting up your own copy of Lorekeeper consists of 3 main steps:

  1. Uploading a copy to your web host
  2. Setting up the database/admin account configuration
  3. Site configuration/adding your ARPG data/modifying the source code

If you have a personal favourite method of setting up your workflow, I would strongly recommend going with what you're comfortable with! Jump ahead to step 2 as there are a few commands you have to run from the command line.

Otherwise, for this tutorial, I'll assume that you have never touched Git and worked on the command line before, and will run through the steps I go through to get this up and working, with my usual workflow. Refer to the basic version of the tutorial to get it uploaded with less fuss, but less convenience working with the source code.

Uploading

We're going to set this up so that we can use Git to manage changes to the site. The setup is based on this article (with a few modifications + expanding on the comments).

Obtaining Local and Server Copies

First, we want to make sure we have the software we need. For Windows PCs, download PuTTY from here and install/set it up (click here for instructions).

Next, we need hosting and a domain name. I'll be using Dreamhost in the examples of this tutorial for hosting.

Set up the domain name so it points to your server. How to do this depends on where your domain name is registered, so check the instructions they should have provided.

Obtain a copy of Lorekeeper. The recommended way to do this is to git clone it on your computer - there are various ways of doing this, but the simplest way is probably to clone it from your Git client. This will also initialise it as a Git repository on your computer. Now, you have a copy of Lorekeeper on your computer that you can use for working. I'll call this your local copy, and the one on your server the server copy (or live site).

We're going to get the code onto the server. Using your SSH client (PuTTY on Windows/Terminal on Mac) SSH into your server - here are Dreamhost's very detailed instructions on how to do that.

From here on, you can enter the commands almost exactly as they are.

Navigate to the directory we're putting the files in.

cd ~

Make a directory for your site - name it whatever you want. In this example I'll use "site-name.com", so replace that with your site name.

mkdir site-name.com
cd site-name.com

Make a directory called www, go in, and git init it.

mkdir www
cd www
git init

Go back out, make a second directory named site_hub.git, and init it as a bare repository.

cd ..
mkdir site_hub.git
cd site_hub.git
git --bare init

Go to your Git client (e.g. Sourcetree as suggested above), select your folder containing Lorekeeper's code and add site_hub.git as a remote. The address is similar to your SSH address but points directly to the folder, something like

ssh://username@host.com/~/site-name.com/site_hub.git

If successful, push the code to the remote. In Sourcetree, right click on the remote, choose to push, select the main branch and click OK.

Back in the SSH client, we'll add site_hub.git as a remote for www.

cd ../www
git remote add hub ../site_hub.git

At this point if you enter

git remote show hub

, you should see something like

* remote hub
   URL: /home/your_username/site-name.com/site_hub.git

Run a git pull.

git pull hub main

Wait for it to finish running, and if it looks like nothing went wrong, enter

ls

and see that there are files inside the directory.

Git Hooks

If everything looks good, we'll set up git hooks so that updating the site is as easy as pushing a button.

Continue by entering

cd .git/hooks
nano post-commit

This will bring up a blank text editor. Enter the following text:

#!/bin/sh
 
 echo
 echo "**** Pushing changes to Hub [Prime's post-commit hook]"
 echo
 
 git push hub

To save the file, enter in order: Ctrl + X, y, enter.

Then, we'll change the permissions on the file:

chmod +x post-commit

We'll also add a hook in site_hub.git.

cd ../../../site_hub.git/hooks
 nano post-update

The contents of this file (note the directory name you have to edit below!!):

#!/bin/sh
 
 echo
 echo "**** Pulling changes into Prime [Hub's post-update hook]"
 echo
 
 cd $HOME/site-name.com/www || exit
 unset GIT_DIR
 git pull hub main
 
 exec git-update-server-info

Once again: Ctrl + X, y, enter.

And again, we'll change the permissions on the file:

chmod +x post-update

You can now test the hooks by modifying something harmless on your local copy (such as a comment, or adding small text file) and commit/pushing the change to the server.

If set up correctly, the output log should display the message you wrote in post-update and show that the file was updated without errors.

For a small but important tweak, we'll change the origin of our repository to point to the new site.

  1. Checkout the site's main branch.
  2. Rename the old origin branch.
  3. Change the site's main branch to origin.

In the future, you (and other users who have access to the repository) can simply push new changes to the code through your Git client at the click of a button, which also keeps track of files that you've added and/or modified, and contains a log of who made what changes to the code. Hooray!

Setting Up

Web Directory

Update your domain to point to the www/public folder.

For DreamHost users, this is under Manage Domains > Edit > Web directory. The page may take a few hours to update, and display an error if you have not completely finished the setup yet (this is normal).

Install Composer

Packages for the project are installed through Composer.

Instructions for installing Composer on your server are here. I recommend following the global instructions. If you follow the local setup, place composer.phar in the www directory.

Additionally, if you're using DreamHost, you will want to change the default PHP version for convenience. See here for instructions.

Packages and Database Setup

In your SSH client, navigate to the www folder and run composer install.

cd ~/site-name.com/www
composer install

Let it finish running. After that, we'll set up the database.

If you're not on DreamHost:

This is easiest through phpMyAdmin, so navigate to your site's phpMyAdmin in your browser.

Click on "Databases" in the top bar, and add a database - it can be called anything you like.

If you're on DreamHost, go to the control panel to set up a database. Be sure to choose names and a password that cannot be easily guessed and note them down! You will need the database name, database user (the New Username field) and database user password (the New Password field) later. The hostname can be used to access PHPMyAdmin - note this down as well.

API Keys

Now, we need to get access to services that will allow us to send e-mails (for registration/resetting passwords) and connect to various social media, etc. platforms (for verifying accounts).

For a small site with little traffic, I'd suggest SendGrid (100 mails a day on their free plan), though you can use any service that you like.

SendGrid Setup

If you're using Sendgrid, after you've created your account, go to API Keys under Settings in the Control Panel and create a new key. Note down the generated SendGrid API key as we'll need it later. Keep this a secret!

Note that you will need to verify your domain. See here for more information.

Social Media Platforms

As of 2.0.0, there are several options for platforms to use for account linking/verification. See Category:Social Media Authentication for instructions for supported sites. Note that you will also need to enable these via config file later. Note that you must set up and enable at least one of these platforms for use for auth.

.env

Now, let's use that information. The site requires a file named .env to be placed in the root directory (in www). Create this file locally, with the following contents/filling out the fields as noted (avoid using spaces in names):

APP_NAME=site_name_with_no_spaces
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=http://site-name.com

CONTACT_ADDRESS=your_contact_address@site-name.com
DEVIANTART_ACCOUNT=your-dA-group-account-username
 
LOG_CHANNEL=stack
DB_CONNECTION=mysql
DB_HOST=your_database_hostname
DB_PORT=3306
DB_DATABASE=your_server_database_name
DB_USERNAME=your_server_database_user_name
DB_PASSWORD=your_server_database_user_password

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.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your_sendgrid_api_key
MAIL_FROM_ADDRESS=noreply@site-name.com
MAIL_FROM_NAME=mail_sender_name

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_DEFAULT_REGION=
AWS_BUCKET=

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

Leave the APP_KEY blank, as it will be generated in a later step. Also make sure to add information for the platform(s) used for auth to the end as in the platform-specific instructions!

Now, use an FTP client (WinSCP if following the recommendations) to upload this file to the www directory of your site. Note that this is the only file that should be added or modified this way; all other files must be modified locally and pushed to the server with git.

Command Line Setup

Moving on to command line setup - now that we have the files in place, we're going to create the database tables, insert some basic required data, and get the crons (scheduled scripts; primarily for scheduled news posts) working.

Run the following, letting each complete before the next one:

php artisan key:generate 
php artisan migrate

This will generate the app key (used for encryption) and create the database tables.

Run the following commands afterwards:

php artisan add-site-settings
php artisan add-text-pages
php artisan copy-default-images

Then, we'll set up the admin user:

php artisan setup-admin-user

This will prompt you for the creation of the admin account, which will have access to all site data. On the live site, I would recommend using this as a purely administrative account and not the site owner's personal account. You can run this command again to change the email address and password of the account.

At this point, you should be able to log into the site with the admin account.

Cron Jobs

Finally, we'll set up the crons so we can make use of scheduling.

For non-DreamHost users:

Refer to this article for how to edit the crontab file.

Add the following line, editing the directory name as necessary:

* * * * * cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1

If you are using DreamHost:

Go to the control panel, click on More > Cron Jobs > Add New Cron Job.

Select the shell user, enter a title (not important; you can set this to your site name for easy identification), and under command to run, add:

cd ~/site-name.com/www && php artisan schedule:run >> /dev/null 2>&1

Then choose the following options:

When to run: Custom

Minutes: Selected Minutes

In the combo box, choose every multiple of 5. DreamHost restricts cron jobs to run every 5 minutes at the very least, so unfortunately you can't get to-the-minute accuracy.

If you can view the site from the URL - congratulations, you've set up the site successfully!

Site Configuration

Before we start adding data, let's edit the config files in the code, making use of Git to send your updates to the server.

Config Files

In your local copy, open up config/app.php in your text editor of choice. The code is commented in detail, so you can read and modify the config as you need. Most settings do not need to be touched since you wrote them in .env, but you may want to edit the timezone to match the clock your community goes by. Note that this must be a PHP-supported time zone-- see here for a list.

It's recommended at this point that you go through the following config files and modify them as desired:

  • config/lorekeeper/settings.php
  • config/lorekeeper/sites.php
    • This is where you enable the sites you set up for authentication use earlier!
  • config/lorekeeper/extensions.php
  • (If desired) config/lorekeeper/group_currency_form.php

Similar to the above, you can read the comments and modify the config files as required.

In your Git client, choose the modified files, commit and push them (important: to your server, not GitHub!) with a helpful message. If the hooks have been set up correctly, you should see the effects on the live site after it's done. If not, and there were no errors, you may need to run

php artisan config:clear

on the server.

Site Data

Now we can start editing the site data. All changes on the live site will only stay on the live site, and all local changes will only remain local.

Log in as the admin user and go to the admin panel (click the crown in the navigation bar). The first things you may want to edit are:

  • Site Settings
  • User Ranks (create moderator ranks)
  • Pages (Terms of Service, Privacy Policy, About)
  • Site Images

You can, of course, dive right into editing the game data - I would recommend editing in the order:

  • rarities
  • categories (trait categories, item categories, prompt categories, character categories)
  • species, traits, items, currencies
  • loot tables
  • prompts, shops

Note that at least 1 character category is required to create any characters. More specific information about each type of data can be found on the respective wiki pages.

Troubleshooting

Please open a ticket in the support Discord for assistance!