From b6b31ad0941e04d0f3d117447e8c116677f1ed95 Mon Sep 17 00:00:00 2001 From: sk1982 Date: Sun, 7 Apr 2024 06:01:26 -0400 Subject: [PATCH] add readmes --- README.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/README.md | 77 +++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 README.md create mode 100644 scripts/README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4bbcdcb --- /dev/null +++ b/README.md @@ -0,0 +1,156 @@ +# Actaeon +An ARTEMiS frontend. + +# **WARNING: Back up your database** +I am not responsible for misconfigurations that lead to database issues. **You should back up your database before making any changes to it.** + +## Creating Database Tables +Before running the database importer script, you must create the tables in your database. This can be done by running the server once with `AUTOMIGRATE` enabled ([see below](#runtime-variables)), or by running `npm run migrate` (make sure you have run `npm i` first and have the [`DATABASE_URL`](#runtime-variables) environment variable set). + +# Building +Make sure you have set the required [build-time variables](#build-time-variables) correctly. + +### Building using Docker +Run `docker compose build` + +### Building without Docker +You may want to specify [runtime variables](#runtime-variables) by modifying `.env.local` +1. Run `npm i` +2. Run `npm run build` + + +# Running +Make sure you have [created tables](#creating-database-tables) and ran [database importer and asset extractor](scripts/README.md). + +### Running using Docker +1. Modify the [runtime environment variables](#runtime-variables) in `docker-compose.yml` +2. Run `docker compose up` (or `docker compose up -d` to detach the output) + +### Running without Docker +1. Run `npm run start` + +## Initial Promotion to Owner +In order to access all features of Actaeon, you need to have owner permissions. This can be done by setting the `permissions` column of your user inside the `aime_user` table to `255`. Once one user is owner, they can promote other users to owner through the Actaeon web interface. + +# Configuration + +Environment variables can be added through `.env.local` or through the environment. At bare minimum, you will need to set the [`NEXT_PUBLIC_*_EXTENSION`](#build-time-variables) variables to the corresponding file extensions generated by the [`asset-extract.py` script](scripts/README.md#asset-configs), along with the [`DATABASE_URL` and `NEXTAUTH_SECRET`](#runtime-variables) variables. + +### Build-time Variables +These variables can only be set at build time: before running `npm run build` or before building the docker image. + +| Variable | Description | Examples | Required | +|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|----------| +| `BASE_PATH` | The base path that the site will be hosted on. Required if you wish to serve the site [through nginx from the same domain as your artemis server](#configuring-nginx-to-serve-actaeon-on-the-same-domain-as-artemis). (default: `/web`) | `/web` | No | +| `ASSET_URL` | The URL or absolute path to where your assets will be hosted. This should be set to `$BASE_PATH/assets` unless you are using a different domain or path to serve assets. (default: `/web/assets`) | `/web/assets`, `/assets` | Yes | +| `NEXT_PUBLIC_JACKET_EXTENSION` | The file extension that jacket images will use. | `.webp`, `.png`, `.avif` | Yes | +| `NEXT_PUBLIC_IMAGE_EXTENSION` | The file extension that other images will use. | `.webp`, `.png`, `.avif` | Yes | +| `NEXT_PUBLIC_MUSIC_EXTENSION` | The file extension that music will use. | `.opus`, `.m4a` | Yes | +| `NEXT_PUBLIC_AUDIO_EXTENSION` | The file extension that other audio will use. | `.opus`, `.m4a` | Yes | + +### Runtime Variables +These variables can be set at runtime through the environment or through the `.env.local` file + +| Variable | Description | Examples | Required | +|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|----------| +| `DATABASE_URL` | URL to your artemis database, in the format `mysql://user:pass@host:port/db_name` | `mysql://aime:aime@127.0.0.1:3306/aime` | Yes | +| `NEXTAUTH_SECRET` or `AUTH_SECRET` | Set this to a long random string (you can generate this by running `openssl rand -base64 32` or `npx auth secret` on the command line) | | Yes | +| `AUTOMIGRATE` | Automatically run new migrations on server startup | `true`, `false` | No | +| `COOKIE_SECURE` | Override the secure flag on authentication cookies (by default, the host protocol or the `x-forwarded-proto` header is used to determine this) | `true`, `false` | No | +| `BCRYPT_ROUNDS` | The number of bcrypt rounds to hash passwords with (default: 12) | `12`, `14` | No | + +## Configuring nginx to serve Actaeon on the same domain as ARTEMiS +Nginx can be configured to serve Actaeon and ARTEMiS on the same domain. To do this, the [`BASE_PATH`](#build-time-variables) variable must be set to a non-root base path (for example, `/web`). + +Your nginx config likely looks similar to this: + +``` +server { + listen 80; + server_name your.hostname.here; + + location / { + # ... + proxy_pass http://127.0.0.1:8080/; + } +} + +server { + listen 443 ssl; + server_name your.hostname.here; + + # ... + + location / { + # ... + proxy_pass http://127.0.0.1:8080/; + } +} +``` + +You can serve Actaeon by adding some additional location blocks. Nginx must also have read access to Actaeon's assets. The following configs assume a base path of `/web`: + +``` +server { + listen 80; + server_name your.hostname.here; + + # redirect to https + location = / { + return 301 https://$host/; + } + + location /web/ { + return 301 https://$host$request_uri; + } + + location / { + # ... + proxy_pass http://127.0.0.1:8080/; + } +} + +server { + listen 443 ssl; + server_name your.hostname.here; + + # ... + + # redirect root to web + rewrite ^/$ /web/ last; + + # serve assets + location /web/assets/ { + # modify this path + alias /path/to/actaeon/public/assets/; + try_files $uri =404; + } + + # uncomment if you want nginx to server nextjs static files + # you will have to run ./docker-transfer-next-static.sh if running through docker + #location /web/_next/static/ { + # # uncomment this if you have ngx_http_gzip_static_module + # #gzip_static on; + # #gzip_vary on; + # # uncomment this if you have ngx_http_brotli_static_module + # #brotli_static on; + # + # # modify this path + # alias /path/to/actaeon/.next/static/; + # try_files $uri =404; + #} + + # actaeon + location /web { + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + proxy_pass http://127.0.0.1:1430; + } + + location / { + # ... + proxy_pass http://127.0.0.1:8080/; + } +} +``` \ No newline at end of file diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..00d528e --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,77 @@ +# Scripts + +These supporting scripts are used to convert game assets and import information into the database. + +### Installing Dependencies +1. Create a virtualenv by running `py -m venv venv` +2. Run `.\venv\scripts\activate` +3. Install dependencies by running `pip install -r requirements.txt` +4. Before running any script, make sure the virtualenv is activated by running `.\venv\scripts\activate` + +# Asset Extractor +Usage: `py asset-extract.py [options] [game_options]` + +### Prerequisites +You must specify the path to these executables inside `paths.yaml` if they are not already on your path. +1. [`ffmpeg`](https://ffmpeg.org/download.html) +2. [`vgmstream-cli`](https://vgmstream.org/) + +### Asset Configs +You can customize the file extension and ffmpeg arguments of generated files through an `assets.yaml` file. Some exiting assets configs have already been provided. Read the comment in the first line of the file to decide which one you want to use. + +### Options +These options must be specified before the `game` argument + +| Flag | Description | Default | +|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| +| `--config` | Asset config file | `assets.fast.yaml` | +| `--paths` | Paths config file | `paths.yaml` | +| `--processes` | Number of processes to use when converting | Number of cores on your system | +| `-o, --output, --out-dir, --output-dir` | Output directory | `../public/assets` | +| `-n, --no-overwrite` | If set, don't overwrite existing files. (Note: if the script is terminated early, it may leave broken assets that need to be deleted if this flag is set) | (Unset) | +| `--no-music` | If set, don't generate music files | (Unset) | +| `--no-audio` | If set, don't generate other audio files (system voice, etc) | (Unset) | +| `--no-jackets` | If set, don't generate jacket images | (Unset) | +| `--no-images` | If set, don't generate other images (avatar images, etc) | (Unset) | + +## Chunithm Extractor +Usage: `py asset-extract.py [options] chuni --data-dir DATA_DIR --opt-dir OPT_DIR` +### Options +These options must be specified after `chuni` + +| Flag | Description | +|--------------|-------------------------------------------------------------| +| `--data-dir` | Path to data directory, containing A000 (required) | +| `--opt-dir` | Path to options directory, containing A001, etc. (required) | + +#### Example Usage +`py asset-extract.py -n --config assets.fast.yaml chuni --data-dir C:\chuni\app\data --opt-dir C:\chuni\option` + +# Database Importer +Usage: `py db-importer.py [options] [game_options]` + +The database importer requires the `DATABASE_URL` environment variable to be set, which can be set in an `.env` file in the format `DATABASE_URL=mysql://user:pass@host:port/db_name` (see the `--env` option) + +# **WARNING: Back up your database** +I am not responsible for misconfigurations that lead to database issues. **You should back up your database before making any changes to it.** + +### Options +These options must be specified before the `game` argument + +| Flag | Description | Default | +|-------------|----------------------------------------------------------|-----------------| +| `--env, -e` | Path to `.env` file to load `DATABASE_URL` variable from | `../.env.local` | + +## Chunithm Importer +Usage: `py db-importer.py [options] chuni --data-dir DATA_DIR --opt-dir OPT_DIR` + +### Options +These options must be specified after `chuni` + +| Flag | Description | +|--------------|-------------------------------------------------------------| +| `--data-dir` | Path to data directory, containing A000 (required) | +| `--opt-dir` | Path to options directory, containing A001, etc. (required) | + +#### Example Usage +`py db-import.py -e ../.env.local chuni --data-dir C:\chuni\app\data --opt-dir C:\chuni\option`