mirror of
https://github.com/janishutz/libreevent.git
synced 2025-11-25 05:14:23 +00:00
progress on docs, fixes in basic setup
This commit is contained in:
50
website/dist/docs/setup/installation/index.html
vendored
50
website/dist/docs/setup/installation/index.html
vendored
@@ -20,56 +20,40 @@
|
||||
<h1>Installation</h1>
|
||||
<p>Let's begin with setting up libreevent! If you are not technically savvy or want somebody else to set it up for you, please contact me <a href="https://api.janishutz.com/contact/setup?origin=libreevent&campaign=installation-docs">here</a>. If you want to set it up yourself, read on below! Soon, there will also be a video tutorial available.</p>
|
||||
<h1>Selecting a webhosting company</h1>
|
||||
<p>Choosing the right hosting provider is not easy, especially since libreevent requires node.js. Therefore, we've listed a few really good options. Whatever hosting provider you end up going with, it is important that they explicitly list Node.js as a feature of that hosting account. All hosting providers below also include MySQL which is beneficial to have and a must-have when you are expecting to sell a lot of tickets simultaneously. This website here is hosted by asurahosting. <em>Note: I may receive a small commission when you buy webhosting using one of the links provided below. This won't affect the price you pay.</em>
|
||||
https://clients.asurahosting.com/aff.php?aff=1997
|
||||
https://www.novatrend.ch/en/
|
||||
https://www.hostinger.com/
|
||||
https://www.a2hosting.com/
|
||||
https://www.hetzner.com/
|
||||
https://www.digitalocean.com/</p>
|
||||
<p><em>Affiliate program</em>
|
||||
<p>Choosing the right hosting provider is not easy, especially since libreevent requires node.js. Therefore, we've listed a few really good options. Whatever hosting provider you end up going with, it is important that they explicitly list Node.js as a feature of that hosting account. All hosting providers below also include MySQL which is beneficial to have and a must-have when you are expecting to sell a lot of tickets simultaneously. This website here is hosted by asurahosting. <em>Note: I may receive a small commission when you buy webhosting using one of the links provided below. This won't affect the price you pay.</em></p>
|
||||
<ul>
|
||||
<li><a href="https://clients.asurahosting.com/aff.php?aff=1997">asurahosting</a></li>
|
||||
<li><a href="https://www.novatrend.ch/en/">novatrend</a></li>
|
||||
<li><a href="https://www.hetzner.com/">hetzner</a> (though make sure that you have a sufficiently high-end account!)</li>
|
||||
</ul>
|
||||
<p><em>Affiliate programs: TODO: Sign up</em>
|
||||
https://affiliates.hostinger.com/users/signup/
|
||||
https://www.a2hosting.com/about/affiliate-program/
|
||||
https://www.digitalocean.com/go/affiliates</p>
|
||||
<h1>Downloading libreevent</h1>
|
||||
<p>We are going to start off by downloading libreevent. On this website, open the navigation menu and head to "Downloads". (We would strongly suggest that you open the link in a new tab by right clicking on the link and hitting "Open in new tab"). Below, hit the download button. This will download a production ready build of libreevent as a zip file. Save it to any convenient location. Head there and extract the zip-Archive (On windows, right click, extract; On MacOS, just double click; on Linux, there is either a zip utility installed or otherwise use the unzip utility in the terminal).</p>
|
||||
<h2>Database</h2>
|
||||
<p>TODO: Make it so that it's not necessary to mention this here.
|
||||
In the database, all the userdata is stored. libreevent currently supports two different databases, MySQL and a custom database based on JSON. Which one to choose?</p>
|
||||
<p>Generally MySQL, except:</p>
|
||||
<ul>
|
||||
<li>If your organisation is small and does only sell a few tickets at a time, the JSON based database works perfectly fine.</li>
|
||||
<li>Your web hosting plan does not includes MySQL and you've got no access to MySQL in any other way. <em>NOTE: Free MySQL services should NEVER be used in such an application, as most hosting plans include MySQL (or MariaDB, which works similarly) which is much more reliable and if you lose access to the database, you can only access the root account and all other user data (and therefore all user accounts) is lost. The event data is always stored in JSON format as it is more efficient this way.</em></li>
|
||||
</ul>
|
||||
<p><strong>NOTE: The JSON database is really slow and should only be used if you have a small event where you expect to sell less than 5 ticket per minute! The amount of tickets sold per minute that the system can handle really depends on the speed of the server the website runs on.</strong></p>
|
||||
<p>MySQL generally is more time consuming to set up, but we'll run you through the process here to make the process easier for you.</p>
|
||||
<p>If you are using the JSON-DB, continue reading:</p>
|
||||
<p>Head into the folder you have downloaded libreevent into and open the "config" directory. In there you can see a few ".json" files. Open the "settings.config.json" file using a text editor (on Windows you could use Notepad, on MacOS TextEdit and on Linux, I personally like to use Nano or Vim, which are cli only or for graphical ones, use for example gedit).</p>
|
||||
<p>In JSON, data is stored in so-called Key-Value-Pairs. Look for "db" in there and and replace the default "mysql" with "json". Keep this file and folder open and skip the next chapter.</p>
|
||||
<h2>Setting up a MySQL database</h2>
|
||||
<p>At this point, we assume that you have already purchased webhosting and you are logged in to the administration panel of your webhosting provider. This guide will use the Web Control Panel called "Direct Admin", as it is fairly common, along with cPanel. Somewhere, there should be a button that says something like "MySQL Management". Click it, which will bring you to the MySQL-Database management page. Now, create a new database by clicking the "Create new database" (or similar) button which will bring up the database creation tool. Give the database any name you like and give the user any name you like. When creating a password, it is important that this password is long and complicated. What we recommend doing is using a password generator or to essentially "sit" onto your keyboard to get a random string of characters as the password.</p>
|
||||
<p>TODO: Make setup better (including db setup), add notes on setup key
|
||||
Now copy this password and open the download location of libreevent. Inside of the libreevent folder and open the "config" folder and open the file called "db.config.json" using a text editor (on Windows you could use Notepad, on MacOS TextEdit and on Linux, I personally like to use Nano or Vim, which are cli only or for graphical ones, use for example gedit). Now, paste the password between the empty quotes after "password". For the host value type your domain, for the "database" parameter, type the name of the database you just created (including any prefixes shown there) and for the database user, type the username you just created (again, including any prefixes shown in the admin panel).</p>
|
||||
<p>Now hit "Create Database" to actually create the database.</p>
|
||||
<p>And just like that, you have finished setting up your database.</p>
|
||||
<h1>Defining a setup key</h1>
|
||||
<p>libreevent uses what we call a setup key. You need to set this manually, as it needs to be different for every install because otherwise the whole point of this setup key is to prevent unauthorized access to the setup program. The setup will be disabled once you have first completed it.</p>
|
||||
<p>To set the setup key, navigate to the extracted libreevent folder and open it. In there you should find a file called "setupkey.txt". Open it up and add any random assortment of characters and numbers in there. What we recommend is that you just roll your hand over your keyboard in any way you like as this generates a very much unpredictable assortment of characters. Then, hit Ctrl + S (or Command + S on MacOS) to save the file. We would recommend leaving this file open, as you will need the setup key at a later point.</p>
|
||||
<h1>Uploading libreevent</h1>
|
||||
<p>It is now time to upload libreevent to your webhosting account. The recommended way of doing this is to download a FTP client like "FileZilla" and to connect to the hosting account in that way using the credentials provided by the hosting provider. In this guide we assume you use this way.</p>
|
||||
<p>Download and install FileZilla. It is a free and open source FTP client. Open it and you will see a few empty fields towards the top of the app. There you will need to fill in the information given by your hosting provider. Usually, the Host is ftp.yourDomain.com, the username and password are usually your admin account credentials and the port is usually 25552 or can be left empty. Then hit quick connect. At this point, a SSL warning might appear, as the certificate might not (yet) be configured correctly to also include FTP. Accept the certificate and you should be connected.</p>
|
||||
<p>It is now time to upload libreevent to your webhosting account. The recommended way of doing this is to download an FTP client like "FileZilla" and to connect to the hosting account in that way using the credentials provided by the hosting provider. In this guide we assume you use this way.</p>
|
||||
<p>Download and install FileZilla <a href="https://filezilla-project.org/download.php?platform=win64">for Windows (64-bit)</a>, <a href="https://filezilla-project.org/download.php?platform=osx">for MacOS</a> or for Linux (available in all major distro repos). It is a free and open source FTP client. Open it and you will see a few empty fields towards the top of the app. There you will need to fill in the information given by your hosting provider. Usually, the Host is ftp.yourDomain.com, the username and password are usually your admin account credentials and the port is usually 25552 or can be left empty. Then hit quick connect. At this point, a SSL warning might appear, as the certificate might not (yet) be configured correctly to also include FTP. Accept the certificate and you should be connected.</p>
|
||||
<p>Now create a new folder called "libreevent" by right clicking onto the empty space on the right pane (where it says "remote site") and selecting "create directory". Then on the left side (where it says "local side" navigate to the extracted libreevent folder and upload its contents by selecting it and right clicking to hitting "Upload"). Once that process is completed, you should be set to go to the next session.</p>
|
||||
<p><strong>IMPORTANT:</strong> Never upload libreevent into any public_html folders ever! This poses a SEVERE security risk and, if a JSON database is used, exposes ALL userdata to the internet! Always upload to a non-publicly accessible folder!</p>
|
||||
<h2>npm install</h2>
|
||||
<p>This project relies on a variety of different node.js modules that need to be installed on the server. Most webhosting providers give you an easy way to run <em>npm install</em>. If not, you might be required to upload the <em>node_modules</em> folder yourself. You can create such a folder either by downloading the <em>node_modules.zip</em> folder from the GitHub releases page or by installing npm on your local machine and then by running <em>npm i</em> in the terminal.</p>
|
||||
<p>This project relies on a variety of different node.js modules that need to be installed on the server. Most webhosting providers give you an easy way to run <em>npm install</em>. If not, you might be required to upload the <em>node_modules</em> folder yourself. You can create such a folder either by downloading the <em>node_modules.zip</em> folder from the Download page or by installing npm on your local machine and then by running <em>npm i</em> in the terminal.</p>
|
||||
<p>To set up the node application in most hosting providers, head to the admin panel of your hosting account once again. Navigate to the main page and scroll down until you find something that says "Setup Node.js App". Click it and wait for it to load. Click "Create Application" and select the newest available Node.js version and set the Application mode to "Production". For the application root insert the directory name which you have created just before when uploading.</p>
|
||||
<p>For the Application URL field, click onto "Choose any value" and select an appropriate domain.</p>
|
||||
<p>For the Application startup file type "app.js".</p>
|
||||
<p>In the section "Environment variables" hit "Add Variable" and in the appearing fields type beneath "Name" the following: "PORT" (without the quotes!) and under "Value" "8080" (again without quotes). Then hit done and at the top "create". If you end up on the start page again, hit the little pencil icon to get to the application editor. Scroll down to the "Detected configuration files" section and click "Run NPM Install". Once it shows a success message (at the top!), hit "Restart".</p>
|
||||
<p>CONGRATULATIONS! You are all set with the installation of libreevent! Now open a new tab in your webbrowser and type your domain name. If you can connect to your domain and libreevent is accessible, you are all set!</p>
|
||||
<p>You may now continue reading the <a href="/docs/setup/setup">Setup guide</a></p>
|
||||
<h1>Troubleshooting</h1>
|
||||
<p>Here are some tips for the most common problems that might arise from the installation</p>
|
||||
<h2>Not accessible, but running</h2>
|
||||
<p>Some with some webhosting companies you need to remove the index.html file from the public_html directory of the domain you are running libreevent on.</p>
|
||||
<h2>A placeholder is shown</h2>
|
||||
<p>With some webhosting companies you need to remove the index.html file from the public_html directory of the domain you are running libreevent on.</p>
|
||||
<h2>Can access all libreevent backend files</h2>
|
||||
<p>You have most likely uploaded libreevent into the public_html file which you should NEVER do, as it poses an insane security risk. Delete it from that folder and put it into a different folder which is not publicly accessible.</p>
|
||||
<p>You have most likely uploaded libreevent into the public_html file which you should NEVER EVER do, as it poses an insane security risk. Delete it from that folder and put it into a different folder which is not publicly accessible.</p>
|
||||
<h2>libreevent doesn't start</h2>
|
||||
<p>On most webhosting accounts, there's a file created in the directory of libreevent called something like stderr.log. Have a look at that file and compare errors with the ones listed here:</p>
|
||||
<h3>DB HAS TO USE InnoDB!</h3>
|
||||
|
||||
25
website/dist/docs/setup/post-setup/index.html
vendored
Normal file
25
website/dist/docs/setup/post-setup/index.html
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title> :: docs - libreevent</title>
|
||||
<link rel="stylesheet" href="/docs/css/style.css">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta charset="utf-8">
|
||||
<meta name="description" content="Looking for a free and open source event management solution you can host yourself? libreevent is a project that does exactly that.">
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/dark.min.css">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
|
||||
<script>hljs.highlightAll();</script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="nav"></div>
|
||||
<div id="side-bar"></div>
|
||||
<div id="backToTop" onclick="backToTop();"></div>
|
||||
<div id="docPage">
|
||||
<div id="doc-container">
|
||||
</div>
|
||||
</div>
|
||||
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.1/jquery.min.js"></script>
|
||||
<script src="/docs/js/index.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
4
website/dist/docs/setup/security/index.html
vendored
4
website/dist/docs/setup/security/index.html
vendored
@@ -18,9 +18,9 @@
|
||||
<div id="docPage">
|
||||
<div id="doc-container">
|
||||
<h1>Security best practices</h1>
|
||||
<p>Whilst libreevent uses modern security features, no Software is perfect when it comes to security. This is why it is important to keep libreevent updated, as potential security issues are addressed with them, as well as potential bugs. Next to that, a incorrectly set up instance of libreevent might pose a security problem, but we try to make the attack surface as small as possible. The most significant security risk that can arise from improperly setting up libreevent is not using HTTPS for the server.</p>
|
||||
<p>Whilst libreevent uses modern security features, no Software is perfect when it comes to security. This is why it is important to keep libreevent updated, as potential security issues are addressed with them, as well as potential bugs. Next to that, an incorrectly set up instance of libreevent might pose a security problem, but we try to make the attack surface as small as possible. The most significant security risk that can arise from improperly setting up libreevent is not using HTTPS for the server.</p>
|
||||
<h2>Reverse Proxy</h2>
|
||||
<p>For simplicity reasons, libreevent does not (yet) natively support SSL-Certificates. This is why libreevent should be put behind a reverse proxy to ensure that all users use SSL (Secure Sockets Layer) or TLS (Transport Layer Security) when connecting to it. Most webhosting plans are already behind a reverse proxy, you will just need to force a HTTPS redirect in the settings of the admin panel of the webhosting account. If you are manually deploying libreevent on a server without a reverse proxy, we urge you to use a reverse proxy with e.g. nginx or apache. There are a lot of guides out there on how to set a such up. Please also get yourself a Certificate for your domain and activate it. A common methods for acquiring such Certificates is to use the "Certbot" CLI application on Linux. It works with both apache and nginx and can automatically renew the certificate for you once it expires if set to run on a cronjob.</p>
|
||||
<p>For simplicity reasons, libreevent does not (yet) natively support SSL-Certificates. This is why libreevent should be put behind a reverse proxy to ensure that all users use SSL (Secure Sockets Layer) or TLS (Transport Layer Security) when connecting to it. Most webhosting plans are already behind a reverse proxy, you will just need to force a HTTPS redirect in the settings of the admin panel of the webhosting account. If you are manually deploying libreevent on a server without a reverse proxy, we urge you to use a reverse proxy with e.g. nginx or apache. There are a lot of guides out there on how to set a such up. Please also get yourself a Certificate for your domain and activate it. A common methods for acquiring such Certificates is to use the "Certbot" CLI application on Linux. It works with both apache and nginx and can automatically renew the certificate for you once it expires if set to run on a cronjob (highly recommended).</p>
|
||||
<h2>HTTPS</h2>
|
||||
<p>As mentioned previously in the Reverse Proxy section, you should always have HTTPS enabled using a reverse proxy. Since most hosting accounts already have a reverse proxy installed, you just need to set it to automatically redirect HTTP to HTTPS in the webhosting admin panel.</p>
|
||||
</div>
|
||||
|
||||
38
website/dist/docs/setup/setup/index.html
vendored
38
website/dist/docs/setup/setup/index.html
vendored
@@ -20,8 +20,30 @@
|
||||
<h1>Setup of libreevent</h1>
|
||||
<p>At this point we assume you've completed the initial install of libreevent. If not, you may find a guide on how to do it <a href="/docs/setup/getting-started">here</a>. Let's get started setting up your event management system!</p>
|
||||
<h2>Connecting to the server</h2>
|
||||
<p>As discussed in the previous part where we installed the system, you can connect to your server simply by opening a web browser and typing your domain name into the address field. After that you should be greeted by the libreevent post-install landing page. Once there, you'll need the setup key you defined during the installation. Type it into the field and hit "Start setup".</p>
|
||||
<p>As discussed in the previous part where we installed the system, you can connect to your server simply by opening a web browser and typing your domain name into the address field. After that you should be greeted by the libreevent post-install landing page. Once there, you'll need the setup key you defined during the installation. Type (or copy) it into the field and hit "Start setup". You will now land on the setup start page. You may hit "Start setup" below to start the setup.</p>
|
||||
<p><em>Note: This is only available during the setup process of libreevent and will afterwards be deactivated to ensure safety of the system.</em></p>
|
||||
<h2>Basic Setup</h2>
|
||||
<p>This page prepares libreevent for use, covering all the basics, the name of the website, database and email accounts.
|
||||
The first setting you may change here is the name of the website. Choose wisely, as changing the name at a later point is hard, not explained in the documentation and also doesn't make for a good image.</p>
|
||||
<h3>Database</h3>
|
||||
<p>In the database, all the userdata is stored. libreevent currently supports two different databases, MySQL and a custom database based on JSON. Which one to choose?</p>
|
||||
<p>Generally MySQL, except:</p>
|
||||
<ul>
|
||||
<li>If your organisation is small and does only sell a few tickets at a time, the JSON based database can be an easy to set up alternative.</li>
|
||||
<li>Your web hosting plan does not includes MySQL and you've got no access to MySQL in any other way. <em>NOTE: Free MySQL services should NEVER be used in such an application, as most hosting plans include MySQL (or MariaDB, which works similarly) which is much more reliable and if you lose access to the database, you can only access the root account and all other user data (and therefore all user accounts) is lost. The event data is always stored in JSON format as it is more efficient this way.</em></li>
|
||||
</ul>
|
||||
<p><strong>NOTE: The JSON database is really slow and should only be used if you have a small event where you expect to sell less than 5 ticket per minute at any time! The amount of tickets sold per minute that the system can handle really depends on the speed of the server the website runs on.</strong></p>
|
||||
<p>MySQL generally is more time consuming to set up (taking about ten minutes compared to zero), but we'll run you through the process here to make the process easier for you.</p>
|
||||
<p>If you are really sure that you want to use the JSON-based database, skip the next section.</p>
|
||||
<h3>Setting up a MySQL database</h3>
|
||||
<p>At this point, we assume that you are logged in to the administration panel of your webhosting provider. This guide will use the Web Control Panel called "Direct Admin", as it is fairly common, along with cPanel. Somewhere, there should be a button that says something like "MySQL Management". Click it, which will bring you to the MySQL-Database management page. Now, create a new database by clicking the "Create new database" (or similar) button which will bring up the database creation tool. Give the database any name you like (libreevent would though be a reasonable choice) and give the user any name you like. When creating a password, it is important that this password is long and complicated. What we recommend doing is using a password generator or to essentially "sit" onto your keyboard to get a random string of characters as the password.</p>
|
||||
<p>Now copy this password and head back to the libreevent setup page. In the "Database host name" field, change the domain, if libreevent hasn't recognized the correct one automatically (do not enter the protocol (like http:// or https://) in the host name field!). Under "database name", enter the name you just entered before when creating the database (including any prefixes shown there) and for the "database user" field, type the username you just created (again, including any prefixes shown in the admin panel). Now paste the password you just copied before into the "Password" field. The port should usually be fine.</p>
|
||||
<p>Now head back to the admin panel of the webhosting provider. Hit "Create Database" to actually create the database.</p>
|
||||
<p>And just like that, you have finished setting up your database.</p>
|
||||
<h3>Email</h3>
|
||||
<p>libreevent needs to have access to an email address to be able to send emails to customers. In the "Account" section, you need to enter the mail connection details. You only need the data for the outgoing mail server, namely for a SMTP server, as this is what libreevent uses.</p>
|
||||
<p>In the "display" section, you can customize how the email address shows up for customers. What we are doing here is known as email address spoofing, if you change what email address is shown. This is being shunned actively by some email providers, which means, the value entered in the "Email address to show" field should be the same as the actual email address. For the display name, you can get creative.</p>
|
||||
<p>With the main part of setup complete, hit continue, to advance to root account setup.</p>
|
||||
<h2>Root account</h2>
|
||||
<p>This is the most powerful account in this system. From it you can control EVERY aspect of your system.</p>
|
||||
<p><strong>Remark: You may (and definitely should) add other accounts with less privileges after completing setup and only use the root account when it is actually necessary</strong></p>
|
||||
@@ -55,17 +77,11 @@
|
||||
</table>
|
||||
<p>Please avoid using easy to guess combinations like names & birth dates of you or your relatives, zip codes & cities and obvious words like 'password', 'libreevent', 'admin', 'root' and your organisation / event's name.</p>
|
||||
<p>After this, the system will email you an email confirmation link using the email you've previously configured in the config.json file during installation.</p>
|
||||
<h2>Page setup</h2>
|
||||
<p>After having set up the root account and confirmed the email address, it is now time to set the name of the webpage. For this, you'll need to enter your organisation's name and choose the offered languages. Note that for every language you select, you need to add a promotional text. Please select a homepage template from <a href="/docs/homepage/templates">here</a>. You also have to upload an/some image(s) at this stage, if the selected template requires (an) image(s).</p>
|
||||
<h2>Payment methods</h2>
|
||||
<p>Now it is time to set up some payment methods. You may find advantages / disadvantages of each payment gateway <a href="/docs/payments">here</a>. It is advised to only choose one payment gateway which provides lots of different payment options, but cost of usage can also be a factor to consider. You may add more payment options by downloading a plugin through the plugin installer in the admin panel. <em>Note: You'll have to restart the node app whenever you install a new plugin!</em></p>
|
||||
<h2>Event setup</h2>
|
||||
<p>With payment methods sorted, you now have to add an event. For this, you'll need to create tickets by hitting the plus icon.</p>
|
||||
<h2>TOS</h2>
|
||||
<p>This is an optional step. Here you may add your own terms of services (TOS), next to the ones that are given by libreevent itself. Your TOS will be inserted at the top.</p>
|
||||
<h2>Setup complete</h2>
|
||||
<p>With this, you've completed the setup of the event. We now ask you to restart the node application. You may do this by stopping the process (if logged in via SSH, press Ctrl + C, if you've got a graphical user interface for setting up the node app, it should be self explanatory) and restarting it as described <a href="/docs/setup/installation#starting">here</a>.</p>
|
||||
<p><strong>Congratulations! You've now successfully set up your event management solution. You may now log into the admin panel. You can find your admin panel at /admin (example: libreevent.janishutz.com/admin, replace libreevent.janishutz.com with your own domain).</strong></p>
|
||||
<p>With this, you've completed the setup of the event. We now ask you to restart the node application. You may do this by stopping the process (if logged in via SSH, press Ctrl + C, if you've got a graphical user interface for setting up the node app, it should be self explanatory) and restarting it.</p>
|
||||
<p>libreevent already gives you the link to the admin panel, which you can click, but if you already closed the page, here's how to reach it:</p>
|
||||
<p><em>You can find your admin panel at /admin (example: libreevent.janishutz.com/admin, replace libreevent.janishutz.com with your own domain).</em></p>
|
||||
<p><strong>Congratulations! You've now successfully set up your event management solution.</strong></p>
|
||||
<p><em>You may find documentation on the admin panel <a href="/docs/admin-panel/">here</a></em></p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
1
website/dist/docs/side-bar.html
vendored
1
website/dist/docs/side-bar.html
vendored
@@ -37,6 +37,7 @@
|
||||
<div class="side-dropdown" id="setup-dropdown">
|
||||
<a class="side-nav-subitem" id="setup" href="/docs/setup">Getting Started</a>
|
||||
<a class="side-nav-subitem" id="setup-installation" href="/docs/setup/installation">Installation</a>
|
||||
<a class="side-nav-subitem" id="setup-post-setup" href="/docs/setup/post-setup"></a>
|
||||
<a class="side-nav-subitem" id="setup-security" href="/docs/setup/security">Security best practices</a>
|
||||
<a class="side-nav-subitem" id="setup-setup" href="/docs/setup/setup">Setup of libreevent</a>
|
||||
<a class="side-nav-subitem" id="setup-update" href="/docs/setup/update">Updating</a>
|
||||
|
||||
3
website/dist/docs/sponsoring/index.html
vendored
3
website/dist/docs/sponsoring/index.html
vendored
@@ -18,7 +18,8 @@
|
||||
<div id="docPage">
|
||||
<div id="doc-container">
|
||||
<h1>Sponsoring</h1>
|
||||
<p>As any project, libreevent also needs funding to keep development going. If you have used and liked libreevent and want to see it grow and become more rich in features, you might want to consider donating to the project.</p>
|
||||
<p>As any project, libreevent also needs funding to keep development going. If you have used and liked libreevent and want to see it grow and become more feature rich, you might want to consider donating to the project. If you are a company and you want to become a sponsor of the project, please <a href="mailto:development@janishutz.com">contact me</a> for a sponsor deal.</p>
|
||||
<p><!-- If you are an individual looking to support the development of libreevent, you may donate [here] TODO: Finish --></p>
|
||||
</div>
|
||||
</div>
|
||||
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.1/jquery.min.js"></script>
|
||||
|
||||
@@ -4,14 +4,11 @@ Let's begin with setting up libreevent! If you are not technically savvy or want
|
||||
|
||||
# Selecting a webhosting company
|
||||
Choosing the right hosting provider is not easy, especially since libreevent requires node.js. Therefore, we've listed a few really good options. Whatever hosting provider you end up going with, it is important that they explicitly list Node.js as a feature of that hosting account. All hosting providers below also include MySQL which is beneficial to have and a must-have when you are expecting to sell a lot of tickets simultaneously. This website here is hosted by asurahosting. *Note: I may receive a small commission when you buy webhosting using one of the links provided below. This won't affect the price you pay.*
|
||||
https://clients.asurahosting.com/aff.php?aff=1997
|
||||
https://www.novatrend.ch/en/
|
||||
https://www.hostinger.com/
|
||||
https://www.a2hosting.com/
|
||||
https://www.hetzner.com/
|
||||
https://www.digitalocean.com/
|
||||
- [asurahosting](https://clients.asurahosting.com/aff.php?aff=1997)
|
||||
- [novatrend](https://www.novatrend.ch/en/)
|
||||
- [hetzner](https://www.hetzner.com/) (though make sure that you have a sufficiently high-end account!)
|
||||
|
||||
*Affiliate program*
|
||||
*Affiliate programs: TODO: Sign up*
|
||||
https://affiliates.hostinger.com/users/signup/
|
||||
https://www.a2hosting.com/about/affiliate-program/
|
||||
https://www.digitalocean.com/go/affiliates
|
||||
@@ -20,41 +17,17 @@ https://www.digitalocean.com/go/affiliates
|
||||
# Downloading libreevent
|
||||
We are going to start off by downloading libreevent. On this website, open the navigation menu and head to "Downloads". (We would strongly suggest that you open the link in a new tab by right clicking on the link and hitting "Open in new tab"). Below, hit the download button. This will download a production ready build of libreevent as a zip file. Save it to any convenient location. Head there and extract the zip-Archive (On windows, right click, extract; On MacOS, just double click; on Linux, there is either a zip utility installed or otherwise use the unzip utility in the terminal).
|
||||
|
||||
## Database
|
||||
|
||||
TODO: Make it so that it's not necessary to mention this here.
|
||||
In the database, all the userdata is stored. libreevent currently supports two different databases, MySQL and a custom database based on JSON. Which one to choose?
|
||||
# Defining a setup key
|
||||
libreevent uses what we call a setup key. You need to set this manually, as it needs to be different for every install because otherwise the whole point of this setup key is to prevent unauthorized access to the setup program. The setup will be disabled once you have first completed it.
|
||||
|
||||
Generally MySQL, except:
|
||||
- If your organisation is small and does only sell a few tickets at a time, the JSON based database works perfectly fine.
|
||||
- Your web hosting plan does not includes MySQL and you've got no access to MySQL in any other way. *NOTE: Free MySQL services should NEVER be used in such an application, as most hosting plans include MySQL (or MariaDB, which works similarly) which is much more reliable and if you lose access to the database, you can only access the root account and all other user data (and therefore all user accounts) is lost. The event data is always stored in JSON format as it is more efficient this way.*
|
||||
|
||||
**NOTE: The JSON database is really slow and should only be used if you have a small event where you expect to sell less than 5 ticket per minute! The amount of tickets sold per minute that the system can handle really depends on the speed of the server the website runs on.**
|
||||
|
||||
MySQL generally is more time consuming to set up, but we'll run you through the process here to make the process easier for you.
|
||||
|
||||
If you are using the JSON-DB, continue reading:
|
||||
|
||||
Head into the folder you have downloaded libreevent into and open the "config" directory. In there you can see a few ".json" files. Open the "settings.config.json" file using a text editor (on Windows you could use Notepad, on MacOS TextEdit and on Linux, I personally like to use Nano or Vim, which are cli only or for graphical ones, use for example gedit).
|
||||
|
||||
In JSON, data is stored in so-called Key-Value-Pairs. Look for "db" in there and and replace the default "mysql" with "json". Keep this file and folder open and skip the next chapter.
|
||||
|
||||
|
||||
## Setting up a MySQL database
|
||||
At this point, we assume that you have already purchased webhosting and you are logged in to the administration panel of your webhosting provider. This guide will use the Web Control Panel called "Direct Admin", as it is fairly common, along with cPanel. Somewhere, there should be a button that says something like "MySQL Management". Click it, which will bring you to the MySQL-Database management page. Now, create a new database by clicking the "Create new database" (or similar) button which will bring up the database creation tool. Give the database any name you like and give the user any name you like. When creating a password, it is important that this password is long and complicated. What we recommend doing is using a password generator or to essentially "sit" onto your keyboard to get a random string of characters as the password.
|
||||
|
||||
TODO: Make setup better (including db setup), add notes on setup key
|
||||
Now copy this password and open the download location of libreevent. Inside of the libreevent folder and open the "config" folder and open the file called "db.config.json" using a text editor (on Windows you could use Notepad, on MacOS TextEdit and on Linux, I personally like to use Nano or Vim, which are cli only or for graphical ones, use for example gedit). Now, paste the password between the empty quotes after "password". For the host value type your domain, for the "database" parameter, type the name of the database you just created (including any prefixes shown there) and for the database user, type the username you just created (again, including any prefixes shown in the admin panel).
|
||||
|
||||
Now hit "Create Database" to actually create the database.
|
||||
|
||||
And just like that, you have finished setting up your database.
|
||||
To set the setup key, navigate to the extracted libreevent folder and open it. In there you should find a file called "setupkey.txt". Open it up and add any random assortment of characters and numbers in there. What we recommend is that you just roll your hand over your keyboard in any way you like as this generates a very much unpredictable assortment of characters. Then, hit Ctrl + S (or Command + S on MacOS) to save the file. We would recommend leaving this file open, as you will need the setup key at a later point.
|
||||
|
||||
|
||||
# Uploading libreevent
|
||||
It is now time to upload libreevent to your webhosting account. The recommended way of doing this is to download a FTP client like "FileZilla" and to connect to the hosting account in that way using the credentials provided by the hosting provider. In this guide we assume you use this way.
|
||||
It is now time to upload libreevent to your webhosting account. The recommended way of doing this is to download an FTP client like "FileZilla" and to connect to the hosting account in that way using the credentials provided by the hosting provider. In this guide we assume you use this way.
|
||||
|
||||
Download and install FileZilla. It is a free and open source FTP client. Open it and you will see a few empty fields towards the top of the app. There you will need to fill in the information given by your hosting provider. Usually, the Host is ftp.yourDomain.com, the username and password are usually your admin account credentials and the port is usually 25552 or can be left empty. Then hit quick connect. At this point, a SSL warning might appear, as the certificate might not (yet) be configured correctly to also include FTP. Accept the certificate and you should be connected.
|
||||
Download and install FileZilla [for Windows (64-bit)](https://filezilla-project.org/download.php?platform=win64), [for MacOS](https://filezilla-project.org/download.php?platform=osx) or for Linux (available in all major distro repos). It is a free and open source FTP client. Open it and you will see a few empty fields towards the top of the app. There you will need to fill in the information given by your hosting provider. Usually, the Host is ftp.yourDomain.com, the username and password are usually your admin account credentials and the port is usually 25552 or can be left empty. Then hit quick connect. At this point, a SSL warning might appear, as the certificate might not (yet) be configured correctly to also include FTP. Accept the certificate and you should be connected.
|
||||
|
||||
Now create a new folder called "libreevent" by right clicking onto the empty space on the right pane (where it says "remote site") and selecting "create directory". Then on the left side (where it says "local side" navigate to the extracted libreevent folder and upload its contents by selecting it and right clicking to hitting "Upload"). Once that process is completed, you should be set to go to the next session.
|
||||
|
||||
@@ -62,7 +35,7 @@ Now create a new folder called "libreevent" by right clicking onto the empty spa
|
||||
|
||||
|
||||
## npm install
|
||||
This project relies on a variety of different node.js modules that need to be installed on the server. Most webhosting providers give you an easy way to run *npm install*. If not, you might be required to upload the *node_modules* folder yourself. You can create such a folder either by downloading the *node_modules.zip* folder from the GitHub releases page or by installing npm on your local machine and then by running *npm i* in the terminal.
|
||||
This project relies on a variety of different node.js modules that need to be installed on the server. Most webhosting providers give you an easy way to run *npm install*. If not, you might be required to upload the *node_modules* folder yourself. You can create such a folder either by downloading the *node_modules.zip* folder from the Download page or by installing npm on your local machine and then by running *npm i* in the terminal.
|
||||
|
||||
To set up the node application in most hosting providers, head to the admin panel of your hosting account once again. Navigate to the main page and scroll down until you find something that says "Setup Node.js App". Click it and wait for it to load. Click "Create Application" and select the newest available Node.js version and set the Application mode to "Production". For the application root insert the directory name which you have created just before when uploading.
|
||||
|
||||
@@ -74,14 +47,17 @@ In the section "Environment variables" hit "Add Variable" and in the appearing f
|
||||
|
||||
CONGRATULATIONS! You are all set with the installation of libreevent! Now open a new tab in your webbrowser and type your domain name. If you can connect to your domain and libreevent is accessible, you are all set!
|
||||
|
||||
You may now continue reading the [Setup guide](&/setup/setup)
|
||||
|
||||
|
||||
# Troubleshooting
|
||||
Here are some tips for the most common problems that might arise from the installation
|
||||
|
||||
## Not accessible, but running
|
||||
Some with some webhosting companies you need to remove the index.html file from the public_html directory of the domain you are running libreevent on.
|
||||
## A placeholder is shown
|
||||
With some webhosting companies you need to remove the index.html file from the public_html directory of the domain you are running libreevent on.
|
||||
|
||||
## Can access all libreevent backend files
|
||||
You have most likely uploaded libreevent into the public_html file which you should NEVER do, as it poses an insane security risk. Delete it from that folder and put it into a different folder which is not publicly accessible.
|
||||
You have most likely uploaded libreevent into the public_html file which you should NEVER EVER do, as it poses an insane security risk. Delete it from that folder and put it into a different folder which is not publicly accessible.
|
||||
|
||||
## libreevent doesn't start
|
||||
On most webhosting accounts, there's a file created in the directory of libreevent called something like stderr.log. Have a look at that file and compare errors with the ones listed here:
|
||||
|
||||
0
website/src/setup/post-setup.md
Normal file
0
website/src/setup/post-setup.md
Normal file
@@ -1,9 +1,9 @@
|
||||
# Security best practices
|
||||
|
||||
Whilst libreevent uses modern security features, no Software is perfect when it comes to security. This is why it is important to keep libreevent updated, as potential security issues are addressed with them, as well as potential bugs. Next to that, a incorrectly set up instance of libreevent might pose a security problem, but we try to make the attack surface as small as possible. The most significant security risk that can arise from improperly setting up libreevent is not using HTTPS for the server.
|
||||
Whilst libreevent uses modern security features, no Software is perfect when it comes to security. This is why it is important to keep libreevent updated, as potential security issues are addressed with them, as well as potential bugs. Next to that, an incorrectly set up instance of libreevent might pose a security problem, but we try to make the attack surface as small as possible. The most significant security risk that can arise from improperly setting up libreevent is not using HTTPS for the server.
|
||||
|
||||
## Reverse Proxy
|
||||
For simplicity reasons, libreevent does not (yet) natively support SSL-Certificates. This is why libreevent should be put behind a reverse proxy to ensure that all users use SSL (Secure Sockets Layer) or TLS (Transport Layer Security) when connecting to it. Most webhosting plans are already behind a reverse proxy, you will just need to force a HTTPS redirect in the settings of the admin panel of the webhosting account. If you are manually deploying libreevent on a server without a reverse proxy, we urge you to use a reverse proxy with e.g. nginx or apache. There are a lot of guides out there on how to set a such up. Please also get yourself a Certificate for your domain and activate it. A common methods for acquiring such Certificates is to use the "Certbot" CLI application on Linux. It works with both apache and nginx and can automatically renew the certificate for you once it expires if set to run on a cronjob.
|
||||
For simplicity reasons, libreevent does not (yet) natively support SSL-Certificates. This is why libreevent should be put behind a reverse proxy to ensure that all users use SSL (Secure Sockets Layer) or TLS (Transport Layer Security) when connecting to it. Most webhosting plans are already behind a reverse proxy, you will just need to force a HTTPS redirect in the settings of the admin panel of the webhosting account. If you are manually deploying libreevent on a server without a reverse proxy, we urge you to use a reverse proxy with e.g. nginx or apache. There are a lot of guides out there on how to set a such up. Please also get yourself a Certificate for your domain and activate it. A common methods for acquiring such Certificates is to use the "Certbot" CLI application on Linux. It works with both apache and nginx and can automatically renew the certificate for you once it expires if set to run on a cronjob (highly recommended).
|
||||
|
||||
## HTTPS
|
||||
As mentioned previously in the Reverse Proxy section, you should always have HTTPS enabled using a reverse proxy. Since most hosting accounts already have a reverse proxy installed, you just need to set it to automatically redirect HTTP to HTTPS in the webhosting admin panel.
|
||||
|
||||
@@ -2,10 +2,44 @@
|
||||
At this point we assume you've completed the initial install of libreevent. If not, you may find a guide on how to do it [here](&/setup/getting-started). Let's get started setting up your event management system!
|
||||
|
||||
## Connecting to the server
|
||||
As discussed in the previous part where we installed the system, you can connect to your server simply by opening a web browser and typing your domain name into the address field. After that you should be greeted by the libreevent post-install landing page. Once there, you'll need the setup key you defined during the installation. Type it into the field and hit "Start setup".
|
||||
As discussed in the previous part where we installed the system, you can connect to your server simply by opening a web browser and typing your domain name into the address field. After that you should be greeted by the libreevent post-install landing page. Once there, you'll need the setup key you defined during the installation. Type (or copy) it into the field and hit "Start setup". You will now land on the setup start page. You may hit "Start setup" below to start the setup.
|
||||
|
||||
*Note: This is only available during the setup process of libreevent and will afterwards be deactivated to ensure safety of the system.*
|
||||
|
||||
## Basic Setup
|
||||
This page prepares libreevent for use, covering all the basics, the name of the website, database and email accounts.
|
||||
The first setting you may change here is the name of the website. Choose wisely, as changing the name at a later point is hard, not explained in the documentation and also doesn't make for a good image.
|
||||
|
||||
### Database
|
||||
In the database, all the userdata is stored. libreevent currently supports two different databases, MySQL and a custom database based on JSON. Which one to choose?
|
||||
|
||||
Generally MySQL, except:
|
||||
- If your organisation is small and does only sell a few tickets at a time, the JSON based database can be an easy to set up alternative.
|
||||
- Your web hosting plan does not includes MySQL and you've got no access to MySQL in any other way. *NOTE: Free MySQL services should NEVER be used in such an application, as most hosting plans include MySQL (or MariaDB, which works similarly) which is much more reliable and if you lose access to the database, you can only access the root account and all other user data (and therefore all user accounts) is lost. The event data is always stored in JSON format as it is more efficient this way.*
|
||||
|
||||
**NOTE: The JSON database is really slow and should only be used if you have a small event where you expect to sell less than 5 ticket per minute at any time! The amount of tickets sold per minute that the system can handle really depends on the speed of the server the website runs on.**
|
||||
|
||||
MySQL generally is more time consuming to set up (taking about ten minutes compared to zero), but we'll run you through the process here to make the process easier for you.
|
||||
|
||||
If you are really sure that you want to use the JSON-based database, skip the next section.
|
||||
|
||||
|
||||
### Setting up a MySQL database
|
||||
At this point, we assume that you are logged in to the administration panel of your webhosting provider. This guide will use the Web Control Panel called "Direct Admin", as it is fairly common, along with cPanel. Somewhere, there should be a button that says something like "MySQL Management". Click it, which will bring you to the MySQL-Database management page. Now, create a new database by clicking the "Create new database" (or similar) button which will bring up the database creation tool. Give the database any name you like (libreevent would though be a reasonable choice) and give the user any name you like. When creating a password, it is important that this password is long and complicated. What we recommend doing is using a password generator or to essentially "sit" onto your keyboard to get a random string of characters as the password.
|
||||
|
||||
Now copy this password and head back to the libreevent setup page. In the "Database host name" field, change the domain, if libreevent hasn't recognized the correct one automatically (do not enter the protocol (like http:// or https://) in the host name field!). Under "database name", enter the name you just entered before when creating the database (including any prefixes shown there) and for the "database user" field, type the username you just created (again, including any prefixes shown in the admin panel). Now paste the password you just copied before into the "Password" field. The port should usually be fine.
|
||||
|
||||
Now head back to the admin panel of the webhosting provider. Hit "Create Database" to actually create the database.
|
||||
|
||||
And just like that, you have finished setting up your database.
|
||||
|
||||
### Email
|
||||
libreevent needs to have access to an email address to be able to send emails to customers. In the "Account" section, you need to enter the mail connection details. You only need the data for the outgoing mail server, namely for a SMTP server, as this is what libreevent uses.
|
||||
|
||||
In the "display" section, you can customize how the email address shows up for customers. What we are doing here is known as email address spoofing, if you change what email address is shown. This is being shunned actively by some email providers, which means, the value entered in the "Email address to show" field should be the same as the actual email address. For the display name, you can get creative.
|
||||
|
||||
With the main part of setup complete, hit continue, to advance to root account setup.
|
||||
|
||||
## Root account
|
||||
This is the most powerful account in this system. From it you can control EVERY aspect of your system.
|
||||
|
||||
@@ -26,23 +60,13 @@ Please avoid using easy to guess combinations like names & birth dates of you or
|
||||
|
||||
After this, the system will email you an email confirmation link using the email you've previously configured in the config.json file during installation.
|
||||
|
||||
## Page setup
|
||||
After having set up the root account and confirmed the email address, it is now time to set the name of the webpage. For this, you'll need to enter your organisation's name and choose the offered languages. Note that for every language you select, you need to add a promotional text. Please select a homepage template from [here](&/homepage/templates). You also have to upload an/some image(s) at this stage, if the selected template requires (an) image(s).
|
||||
|
||||
|
||||
## Payment methods
|
||||
Now it is time to set up some payment methods. You may find advantages / disadvantages of each payment gateway [here](&/payments). It is advised to only choose one payment gateway which provides lots of different payment options, but cost of usage can also be a factor to consider. You may add more payment options by downloading a plugin through the plugin installer in the admin panel. *Note: You'll have to restart the node app whenever you install a new plugin!*
|
||||
|
||||
## Event setup
|
||||
With payment methods sorted, you now have to add an event. For this, you'll need to create tickets by hitting the plus icon.
|
||||
|
||||
## TOS
|
||||
This is an optional step. Here you may add your own terms of services (TOS), next to the ones that are given by libreevent itself. Your TOS will be inserted at the top.
|
||||
|
||||
## Setup complete
|
||||
With this, you've completed the setup of the event. We now ask you to restart the node application. You may do this by stopping the process (if logged in via SSH, press Ctrl + C, if you've got a graphical user interface for setting up the node app, it should be self explanatory) and restarting it as described [here](&/setup/installation#starting).
|
||||
With this, you've completed the setup of the event. We now ask you to restart the node application. You may do this by stopping the process (if logged in via SSH, press Ctrl + C, if you've got a graphical user interface for setting up the node app, it should be self explanatory) and restarting it.
|
||||
|
||||
libreevent already gives you the link to the admin panel, which you can click, but if you already closed the page, here's how to reach it:
|
||||
|
||||
**Congratulations! You've now successfully set up your event management solution. You may now log into the admin panel. You can find your admin panel at /admin (example: libreevent.janishutz.com/admin, replace libreevent.janishutz.com with your own domain).**
|
||||
*You can find your admin panel at /admin (example: libreevent.janishutz.com/admin, replace libreevent.janishutz.com with your own domain).*
|
||||
|
||||
**Congratulations! You've now successfully set up your event management solution.**
|
||||
|
||||
*You may find documentation on the admin panel [here](&/admin-panel/)*
|
||||
@@ -1,3 +1,5 @@
|
||||
# Sponsoring
|
||||
|
||||
As any project, libreevent also needs funding to keep development going. If you have used and liked libreevent and want to see it grow and become more rich in features, you might want to consider donating to the project.
|
||||
As any project, libreevent also needs funding to keep development going. If you have used and liked libreevent and want to see it grow and become more feature rich, you might want to consider donating to the project. If you are a company and you want to become a sponsor of the project, please [contact me](mailto:development@janishutz.com) for a sponsor deal.
|
||||
|
||||
<!-- If you are an individual looking to support the development of libreevent, you may donate [here] TODO: Finish -->
|
||||
Reference in New Issue
Block a user