PSFPortal/README.md

162 lines
6.3 KiB
Markdown
Raw Permalink Normal View History

2019-12-30 19:36:00 +00:00
# PSFPortal
An API + webapp to manage PSForever accounts, characters, and servers.
## Features
* User registration, login, and sessions
* Home page
* Admin management
### Upcoming Features
* Email verification + captcha
* Changing passwords
* WorldServer mangement
## Developing
2020-01-07 17:57:20 +00:00
**This requires a [relatively modern version](https://nodejs.org/en/download/current/) of Node that supports async/await and ES6 (v13.x+). Tested using v13.3.0. Do not use LTS builds.** You may still get `(node:61412) ExperimentalWarning: The ESM module loader is experimental.`. Ignore this as ESM is essentially stable in recent versions.
2019-12-30 19:36:00 +00:00
2020-01-07 18:21:12 +00:00
**Windows users: Before continuing, run `npm install --global --production windows-build-tools`. Otherwise, `bcrypt` won't install properly.**
2019-12-30 19:36:00 +00:00
First download and install the Node dependencies:
```
git clone https://github.com/psforever/PSFPortal
cd PSFPortal/
npm install
```
2020-01-07 18:21:12 +00:00
You should see no errors (warnings are okay).
### Database
Next, install PostgreSQL from your package manager or the following links:
2020-01-09 23:27:56 +00:00
* Windows - [Official Downloads](https://www.postgresql.org/download/windows/)
2020-01-07 18:21:12 +00:00
* Linux - [Debian](https://www.postgresql.org/download/linux/debian/) or [Ubuntu](https://www.postgresql.org/download/linux/ubuntu/)
* macOS - Application https://www.postgresql.org/download/ (or `brew install postgresql && brew services start postgresql`)
Create a database named `psforever` using `psql` or a graphical tool such as [pgAdmin](https://www.pgadmin.org/download/) (highly recommended).
Then create a user named `psforever` with a password of `psforever` and `GRANT` it access to the `psforever` database, public tables, and public sequences.
This can be summarized with the following raw SQL commands:
```sql
CREATE USER psforever;
CREATE DATABASE psforever;
GRANT ALL PRIVILEGES ON DATABASE psforever TO psforever;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO psforever;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO psforever;
ALTER USER psforever WITH PASSWORD 'psforever';
```
Load the DB schema into the database using the command line:
2019-12-30 19:36:00 +00:00
```
psql psforever < db/schema.sql
```
2020-01-07 18:21:12 +00:00
Or the pgAdmin's "Query Tool" interface.
### Running
2020-01-07 17:57:20 +00:00
Before running, you will need to create a `.env` file in the root of the project like this:
2019-12-30 19:36:00 +00:00
```
2020-01-07 17:57:20 +00:00
PGUSER=your_database_user
PGHOST=localhost
PGPASSWORD=your_database_user_password
2020-05-12 21:48:34 +00:00
PSADMIN="127.0.0.1:51002"
2020-01-07 17:57:20 +00:00
PGDATABASE=psforever
PGPORT=5432
COOKIE_SECRET=make_this_very_long_and_random
2019-12-30 19:36:00 +00:00
```
2020-01-07 17:57:20 +00:00
**Never** share/release/commit your `.env` file.
2020-05-12 21:48:34 +00:00
Now run the following command:
2019-12-30 19:36:00 +00:00
```
2020-05-12 21:48:34 +00:00
# Will start the backend server (:8080) and webpack
npm run dev
2019-12-30 19:36:00 +00:00
```
2020-01-07 17:57:20 +00:00
You should see similar output:
```
2020-05-12 21:48:34 +00:00
> psfportal@1.0.0 dev /home/chord/PSFPortal
> concurrently --kill-others "npm run dev-server" "npm run webpack"
[1]
[1] > psfportal@1.0.0 webpack /home/chord/PSFPortal
[1] > webpack-dev-server --history-api-fallback --config webpack.config.cjs --content-base public
[1]
[0]
[0] > psfportal@1.0.0 dev-server /home/chord/PSFPortal
[0] > nodemon -w api/ -w index.js
[0]
[0] [nodemon] 2.0.2
[0] [nodemon] to restart at any time, enter `rs`
[0] [nodemon] watching dir(s): api/**/* index.js
[0] [nodemon] watching extensions: js,mjs,json
[0] [nodemon] starting `node index.js`
[0] (node:16193) ExperimentalWarning: The ESM module loader is experimental.
[0] WARNING: development server simulated delay active
[0] Trusting proxy
[0] Connected to the psql database at localhost
[0] Starting PSAdmin polling for 127.0.0.1:51002
[0] [MODE development] PSFWeb now accepting requests at http://localhost:8080/
[1] 「wds」: Project is running at http://dev.psforever.net:8081/
[1] 「wds」: webpack output is served from /
[1] 「wds」: Content not from webpack is served from /home/chord/PSFPortal/public
[1] 「wds」: 404s will fallback to /index.html
[1] 「wdm」: Hash: 72b56958125b6abdf96c
[1] Version: webpack 4.41.5
[1] Time: 4493ms
[1] Built at: 05/12/2020 11:44:23 PM
[1] Asset Size Chunks Chunk Names
[1] bundle.js 2.1 MiB bundle [emitted] bundle
[1] bundle.js.map 2.23 MiB bundle [emitted] [dev] bundle
[1] Entrypoint bundle = bundle.js bundle.js.map
[1] [1] multi (webpack)-dev-server/client?http://dev.psforever.net:8081 ./app/main.js 40 bytes {bundle} [built]
[1] [./app/App.svelte] 14.5 KiB {bundle} [built]
<snip>
[1] 「wdm」: Compiled successfully.
2020-01-07 17:57:20 +00:00
> psfportal@1.0.0 dev-server
> nodemon -w api/ -w index.js
[nodemon] 2.0.2
[nodemon] to restart at any time, enter `rs`
[nodemon] watching dir(s): api/**/* index.js
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node index.js`
(node:25327) ExperimentalWarning: The ESM module loader is experimental.
WARNING: development server simulated delay active
Connected to the psql database at localhost
[MODE development] PSFWeb now accepting requests at http://localhost:8080/
```
Please note that Webpack (dev) will proxy all API requests (/api) to the host `http://localhost:8080` (see the `devServer` key in [webpack.config.cjs](webpack.config.cjs)). This MUST match your backend server's (dev-server) listening port, which is by default 8080.
**Finally, connect to http://localhost:8081** (webpack, not the raw express server)
Register an account to start and grant it GM privileges using `UPDATE accounts SET gm=true WHERE id=your_id`.
2020-01-07 17:57:20 +00:00
### Troubleshooting
1. Database SELECT/INSERTs are failing, but I can connect to the DB
Make sure you have granted the right permissions to your DB user.
```
GRANT ALL PRIVILEGES ON DATABASE user TO dbname;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO user;
```
2. `[HPM] Error occurred while trying to proxy request /api/stats from localhost:8080 to http://localhost:8080`
Your Webpack instance is listening on 8080, when it should be listening on 8081 and proxying to the express server at 8080. Make sure to run `npm run dev-server` first and make sure it ran properly.
3. `Error: Cannot find package 'bcrypt'`
The `bcrypt` package has native dependencies that must match your Node version. If you upgrade Node, they will be outdated. To fix this, you need to remove your `node_modules/` directory and run `npm install` again to kick off another native build of this dependency.
2019-12-30 19:36:00 +00:00
## Production Running/Building
Follow the same steps as above, but instead run `npm run production` at the very end.