Add installation guide to README
I tried it in my lil Ubuntu WSL box and hey, it worked great! Neat!! Pretty neat to have just sat down and fixed up the dev environment for other people?? I'll see about what it would take to actually invite people in…
This commit is contained in:
parent
b84c8ba34e
commit
d37b7fab2f
2 changed files with 86 additions and 12 deletions
88
README.md
88
README.md
|
|
@ -4,33 +4,105 @@
|
|||
|
||||
This is a rewrite of the Neopets customization app, Dress to Impress!
|
||||
|
||||
It's a React app, built with `create-react-app`, running on Vercel, JAMstack-style.
|
||||
It's a React app, using the Next.js framework. (But kinda awkwardly, because it
|
||||
used to be a `create-react-app`, and we never fully rearchitected from that!)
|
||||
|
||||
The motivating goals of the rewrite are:
|
||||
|
||||
- Mobile friendly, to match Neopets's move to mobile.
|
||||
- Simple modern tech, to be more maintainable over time and decrease hosting costs.
|
||||
|
||||
If you want to contribute, please reach out to Matchu! This repository is _almost_ shareable, but the main limitation is that we currently run even our development server against the production database, and those credentials are private. But we can change that if there's interest!
|
||||
## Installation guide
|
||||
|
||||
### Getting everything set up
|
||||
|
||||
We'll assume you already have your basic development environment ready! Be sure
|
||||
to install the following:
|
||||
|
||||
- Git
|
||||
- Node v16
|
||||
- The Yarn package manager
|
||||
- A MySQL database server
|
||||
|
||||
**Before you clone the repository**, install Git LFS, a tool for managing large
|
||||
files in Git. (We use this for the big batch of public data that we'll import
|
||||
into your dev database.)
|
||||
|
||||
Next, clone this repository, and ensure that
|
||||
`scripts/db/public-data-from-modeling.sql.gz` is around ~30MB large. (If it's
|
||||
much smaller, like 4KB, that probably means Git LFS didn't run correctly, so
|
||||
the next step would be to debug that, delete the repository, and try again!)
|
||||
|
||||
Next, run `yarn install`. This should install the app's NPM dependencies. (You
|
||||
may need to install some additional libraries to your machine for certain
|
||||
dependencies to install correctly. See the instructions for
|
||||
[canvas][npm-canvas] in particular!)
|
||||
|
||||
### Create your development database
|
||||
|
||||
Next, create two MySQL databases: `openneo_impress` and `openneo_id`. Then,
|
||||
create a MySQL user named `impress_2020_dev` with password `impress_2020_dev`,
|
||||
with full permissions for both databases.
|
||||
|
||||
(We're assuming that, on your local machine, your MySQL server isn't connected
|
||||
to the outside internet, and that there probably won't be sensitive information
|
||||
stored in your DTI database anyway, so it should be okay for this username and
|
||||
password to be hardcoded.)
|
||||
|
||||
Finally, run `yarn db:setup-dev:full` to fill the databases
|
||||
with the necessary schema, plus some real public data exported from DTI—like
|
||||
items, species, and colors!
|
||||
|
||||
### See it work!
|
||||
|
||||
Okay, let's run `yarn dev`! This should start a DTI server on port 3000. Open
|
||||
it in your browser and hopefully it works!! 🤞
|
||||
|
||||
### Optional: You might need some environment variables
|
||||
|
||||
In Next.js, you can set environment variables in a `.env` file, in the root of
|
||||
the app. (This will be ignored by Git, thanks to our `.gitignore` file.)
|
||||
|
||||
Note that some the features of the site won't work without special environment
|
||||
variables set, because they depend on production services we can't reproduce
|
||||
locally. But they generally fail gracefully and show a helpful error message,
|
||||
so you mostly won't have to worry about it until you run into it!
|
||||
|
||||
You mostly won't need to use this! But one early case you'll run into: for
|
||||
account creation and login to work, you'll need to create a `.env` file with a
|
||||
value for `DTI_AUTH_TOKEN_SECRET`: a secret string we use to cryptographically
|
||||
validates the user's login cookie. In production this is a closely-guarded
|
||||
secret, but for development, just open a random password generator and
|
||||
copy-paste the result into `.env`!
|
||||
|
||||
```
|
||||
DTI_AUTH_TOKEN_SECRET=jl2DFjkewkrufsIDKwhatever
|
||||
```
|
||||
|
||||
[npm-canvas]: https://www.npmjs.com/package/canvas
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
First, there's the core app, in this repository.
|
||||
- **React app:** Runs on Vercel's CDN. Code in `src/app`.
|
||||
- **API functions:** Run on Vercel's Serverless Functions. Code in `api` and `src/server`.
|
||||
|
||||
- **React app:** Runs mainly on the client's machine. Code in `src/app`.
|
||||
- **API functions:** Run on our VPS server. Code in `api` and `src/server`.
|
||||
|
||||
Then, there's our various data storage components.
|
||||
|
||||
- **MySQL database:** Runs on our Linode VPS, colocated with the old app.
|
||||
- **Amazon S3:** Stores PNGs of pet/item appearance layers, converted from the Neopets SWFs. *(Once Neopets releases HTML5-compatible assets for all their items, we can hopefully remove this!)*
|
||||
- **Amazon S3:** Stores PNGs of pet/item appearance layers, converted from the Neopets SWFs. _(Once Neopets releases HTML5-compatible assets for all their items, we can hopefully remove this!)_
|
||||
|
||||
Finally, there's our third-party integrations.
|
||||
- **Auth0:** For authentication. Data imported from our old OpenNeo ID auth database.
|
||||
|
||||
- **Honeycomb:** For observability & performance insights on the backend.
|
||||
- **Discord:** For logging Support users' actions to a private Discord server.
|
||||
- **Neopets:** We load pet data from them! And plenty of assets!
|
||||
- **Fastly:** A CDN cache that sits in front of our server to help cache common requests and expensive operations. We also use them to proxy for `images.neopets.com` in some cases, so we can add crossdomain headers.
|
||||
|
||||
Notable old components _not_ currently included in Impress 2020:
|
||||
|
||||
- **Elasticsearch:** Used for lightning-fast item search queries. So far, we're finding the MySQL queries to be fast enough in practice. Might consider using some kind of fulltext query engine if that doesn't scale with more users!
|
||||
- **Resque:** Used to schedule background tasks for modeling and outfit thumbnails.
|
||||
- **Outfit thumbnail generation:** Used for outfit thumbnails in the app. I'm wondering if there's a way to get away with not doing this, like just rendering the layers... but I suppose if we want a good social share experience, then we'll probably want this. Maybe we can generate them on the fly as API requests, instead of adding a data storage component?
|
||||
- **Resque:** Used to schedule background tasks for modeling and outfit thumbnails. (We now perform these tasks on-demand, and use Fastly to cache things like thumbnails!)
|
||||
- **Memcache:** Used to cache common HTML and JSON snippets. Not yet needing anything similar in Impress 2020!
|
||||
- **The entire old Rails app!** No references to it in here, aside from some temporary URL links to features that aren't implemented here yet.
|
||||
|
|
|
|||
10
package.json
10
package.json
|
|
@ -62,8 +62,8 @@
|
|||
"scripts": {
|
||||
"prepare": "husky install",
|
||||
"start": "next start",
|
||||
"dev": "yarn build-cached-data && DB_ENV=development REACT_APP_IMPRESS_LOG_IN_AS=$IMPRESS_LOG_IN_AS TS_NODE_COMPILER=typescript-cached-transpile next dev",
|
||||
"local-prod": "yarn build-cached-data && DB_ENV=production REACT_APP_IMPRESS_LOG_IN_AS=$IMPRESS_LOG_IN_AS TS_NODE_COMPILER=typescript-cached-transpile next dev",
|
||||
"dev": "DB_ENV=development yarn build-cached-data && DB_ENV=development REACT_APP_IMPRESS_LOG_IN_AS=$IMPRESS_LOG_IN_AS TS_NODE_COMPILER=typescript-cached-transpile next dev",
|
||||
"local-prod": "DB_ENV=production yarn build-cached-data && DB_ENV=production REACT_APP_IMPRESS_LOG_IN_AS=$IMPRESS_LOG_IN_AS TS_NODE_COMPILER=typescript-cached-transpile next dev",
|
||||
"build": "yarn build-cached-data && next build",
|
||||
"vercel-build": "yum install libuuid-devel libmount-devel && cp /lib64/{libuuid,libmount,libblkid}.so.1 node_modules/canvas/build/Release/",
|
||||
"test": "jest test --env=jsdom",
|
||||
|
|
@ -77,7 +77,7 @@
|
|||
"mysqldump": "mysqldump --host=impress.openneo.net --user=$(dotenv -p IMPRESS_MYSQL_USER) --password=$(dotenv -p IMPRESS_MYSQL_PASSWORD)",
|
||||
"setup-mysql": "yarn mysql-admin < scripts/setup-mysql.sql",
|
||||
"setup-mysql-dev": "yarn mysql-dev < scripts/setup-mysql-dev-constants.sql && yarn mysql-dev < scripts/setup-mysql-dev-schema-impress.sql && yarn mysql-dev --database=openneo_id < scripts/setup-mysql-dev-schema-id.sql",
|
||||
"run-script": "ts-node --compiler=typescript-cached-transpile --transpile-only -r dotenv/config",
|
||||
"run-script": "echo $DB_ENV; ts-node --compiler=typescript-cached-transpile --transpile-only -r dotenv/config",
|
||||
"build-cached-data": "yarn run-script scripts/build-cached-data.js",
|
||||
"cache-asset-manifests": "yarn run-script scripts/cache-asset-manifests.js",
|
||||
"delete-user": "yarn run-script scripts/delete-user.js",
|
||||
|
|
@ -98,7 +98,9 @@
|
|||
"db:export:schema": "./scripts/db/export/schema.sh",
|
||||
"db:export:public-data": "./scripts/db/export/public-data.sh",
|
||||
"db:setup-dev:minimal": "./scripts/db/setup-dev/minimal.sh",
|
||||
"db:setup-dev:full": "./scripts/db/setup-dev/full.sh"
|
||||
"db:setup-dev:full": "./scripts/db/setup-dev/full.sh",
|
||||
"hmm": "echo $FOO",
|
||||
"hmmm": "yarn hmm"
|
||||
},
|
||||
"browserslist": {
|
||||
"production": [
|
||||
|
|
|
|||
Loading…
Reference in a new issue