Difference between revisions of "Tutorial: Setting Up"
(→.env) |
|||
(4 intermediate revisions by the same user not shown) | |||
Line 84: | Line 84: | ||
cd site_hub.git | cd site_hub.git | ||
git --bare init</pre> | 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 <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 | + | 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. | ||
Line 91: | Line 91: | ||
At this point if you enter <pre>git remote show hub</pre>, you should see something like | At this point if you enter <pre>git remote show hub</pre>, you should see something like | ||
<pre>* remote hub | <pre>* remote hub | ||
− | URL: /home/your_username/site-name.com/site_hub.git</pre>Run a git pull.<pre>git pull hub | + | 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. | 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. | ||
Line 125: | 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</pre> | exec git-update-server-info</pre> | ||
Line 139: | Line 139: | ||
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! | ||
Line 186: | Line 186: | ||
===.env=== | ===.env=== | ||
− | Now, let's use that information. The site requires a file named .env to be placed in the root directory | + | 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> | <pre> | ||
Line 244: | Line 244: | ||
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 | <pre>php artisan key:generate | ||
php artisan migrate</pre> | php artisan migrate</pre> |
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!