Difference between revisions of "Tutorial: Setting Up"
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: | ||
− | + | *[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] | ||
− | + | It's 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. | + | *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 | + | **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. | ||
− | + | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Navigate to the directory we're putting the files in. | Navigate to the directory we're putting the files in. | ||
− | < | + | <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. | ||
− | < | + | <pre>mkdir site-name.com |
− | + | cd site-name.com</pre> | |
− | Make a directory called | + | Make a directory called www, go in, and git init it. |
− | < | + | <pre>mkdir www |
− | + | cd www | |
− | + | git init</pre> | |
− | Go back out | + | Go back out, make a second directory named site_hub.git, and init it as a bare repository. |
− | + | <pre>cd .. | |
− | + | mkdir site_hub.git | |
− | + | cd site_hub.git | |
− | + | 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 < | + | 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. |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
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. | ||
− | < | + | <pre>cd ../www |
− | + | git remote add hub ../site_hub.git</pre> | |
− | At this point if you enter < | + | At this point if you enter <pre>git remote show hub</pre>, you should see something like |
− | < | + | <pre>* remote hub |
− | URL: /home/your_username/site-name.com/site_hub.git</ | + | URL: /home/your_username/site-name.com/site_hub.git</pre>Run a git pull.<pre>git pull hub main</pre> |
− | + | 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Run a git pull. | ||
− | |||
− | Wait for it to finish running, and if it looks like nothing went wrong, enter < | ||
− | == Git Hooks == | + | ===Git Hooks=== |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
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 | ||
− | < | + | <pre>cd .git/hooks |
− | + | 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: | ||
− | < | + | <pre>#!/bin/sh |
echo | echo | ||
Line 131: | Line 107: | ||
echo | echo | ||
− | git push hub</ | + | 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: | ||
− | < | + | <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. | ||
− | < | + | <pre>cd ../../../site_hub.git/hooks |
− | nano post-update</ | + | 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!!): | ||
− | < | + | <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 | + | git pull hub main |
− | exec git-update-server-info</ | + | 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: | ||
− | < | + | <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 | + | For a small but important tweak, we'll change the origin of our repository to point to the new site. |
− | # Checkout the site's | + | #Checkout the site's main branch. |
− | # Rename the old origin branch. | + | #Rename the old origin branch. |
− | # Change the site's | + | #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). | ||
− | + | ===Install Composer=== | |
− | + | Packages for the project are installed through 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. | |
− | |||
− | + | 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. | |
− | + | ===Packages and Database Setup=== | |
− | + | In your SSH client, navigate to the www folder and run composer install. | |
− | + | <pre>cd ~/site-name.com/www | |
+ | composer install</pre> | ||
+ | Let it finish running. After that, we'll set up the database. | ||
− | + | If you're not on DreamHost: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | If you're not on DreamHost | ||
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 | + | 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 | + | 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! | ||
− | + | Note that you will need to verify your domain. See [https://docs.sendgrid.com/for-developers/sending-email/sender-identity here] for more information. | |
− | + | ====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. | ||
− | + | ===.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): | ||
− | + | <pre> | |
+ | APP_NAME=site_name_with_no_spaces | ||
+ | APP_ENV=production | ||
+ | APP_KEY= | ||
+ | APP_DEBUG=false | ||
+ | APP_URL=<nowiki>http://site-name.com</nowiki> | ||
− | + | 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}" | |
− | + | </pre> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | 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 ([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.''' |
− | + | ===Command Line Setup=== | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | == 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. | ||
− | + | Run the following, letting each complete before the next one: | |
− | < | + | <pre>php artisan key:generate |
− | + | 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: | ||
− | < | + | <pre>php artisan add-site-settings |
− | + | php artisan add-text-pages | |
− | + | php artisan copy-default-images</pre> | |
Then, we'll set up the admin user: | Then, we'll set up the admin user: | ||
− | < | + | <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: | ||
− | < | + | <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: | ||
− | < | + | <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. |
− | + | 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 | ||
+ | **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== |
− | + | Please open a ticket in the [https://discord.gg/U4JZfsu support Discord] for assistance! | |
− | + | [[Category:Documentation]] | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
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
- Visual Studio Code is recommended!
- 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:
- Uploading a copy to your web host
- Setting up the database/admin account configuration
- 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.
- Checkout the site's main branch.
- Rename the old origin branch.
- 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
- See Galleries for more information
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!