diff --git a/README.md b/README.md index c5ed4dd..298cd3b 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,19 @@ Please note the /status endpoint will be broken with the original servers as COR ```bash ./manage setup ``` -3. Start the server +3. Copy template files and edit them + ```bash + cp docker-compose.yml.example docker-compose.yml # Copy Docker Compose file + cp .env.example .env # Copy env file + + nano docker-compose.yml # Edit Docker Compose (database server) + nano .env # Edit env (database config) + ``` + + When editing .env, use server details from docker-compose.yml so they are linked together. Ensure you double-check the IP or hostname of the Docker container, and link that with the .env file. This is crucial, or your database will not be connected. + + Database features are only for analytics, at this time. +4. Start the server ```bash ./manage up ``` @@ -32,14 +44,59 @@ Please note the /status endpoint will be broken with the original servers as COR Windows is currently not supported by aidxnFUN yet. I suggest you use WSL, and follow the Linux instructions, or purchase a server. # How it works -This website uses NodeJS, ExpressJS for a server, EJS for templating, and Tailwind CSS for the frontend CSS. +This website uses NodeJS, ExpressJS for a server, EJS for templating, and Tailwind CSS for the frontend CSS. It additionally uses Docker (w/ MariaDB and optionally PhpMyAdmin) for managing the database, which is used in the analytics system. The `manage` script uses all of those tools to manage the server for you executes the repetitive tasks for you automatically. -The views contain both regular page shards (full HTML documents) and generic shards. I define a "shard" as an EJS template, and are put together into a pretty little website at the end. +The views contain both regular page shards (full-ish pages) and generic shards (fragments of pages, widgets, etc). I define a "shard" as an EJS template, which are pieced together into a pretty little website. The shards hold individual elements like music widgets, while a regular page shard is the page that contains the music widget, which the end user sees. This is helpful for understanding the code. Thus far, shards are included for a music widget, the header, and the footer of the pages. Music (as featured on the home page) is fetched from an API (hosted on https://biancarosa.com.br), which I am in the process of setting up for myself. It works with a LastFM account (I linked this to my Spotify) and can track your live listening with amazing accuracy. The repo can be found at [biancarosa/lastfm-last-played](https://github.com/biancarosa/lastfm-last-played). +# Sample docker-compose.yml - (suggested) +```dockerfile +services: + aidxnfun-db: + image: mariadb:latest + networks: + aidxnfun-n: + ipv4_address: 10.5.0.5 + environment: + MYSQL_ROOT_PASSWORD: iloveaidxnfun123 + MYSQL_DATABASE: aidxnfun + MYSQL_USER: aidxnfun + MYSQL_PASSWORD: iloveaidxnfun + restart: unless-stopped + phpmyadmin: + image: phpmyadmin + restart: always + networks: + aidxnfun-n: + ipv4_address: 10.5.0.6 + ports: + - 80:80 + environment: + - PMA_ARBITRARY=1 + +networks: + aidxnfun-n: + external: true + ipam: + config: + - subnet: 10.5.0.0/16 + gateway: 10.5.0.1 +``` + +This can be used in conjunction with the example .env file compatible with this file: + +```dotenv +DB_HOST="10.5.0.5" +DB_USER="root" +DB_PASSWORD="iloveaidxnfun123" +DB_NAME="aidxnfun" +``` + +This config will create a MariaDB instance, with a pre-created database, as long well as supplied user credentials. A PhpMyAdmin instance will additionally be spun up for easy management and inspection of the database. You may plug in `10.5.0.5` as the host on [your ip]:80 in your web browser (on the computer running Docker). + # Using the `manage` script You may have noticed you have a `manage` file after cloning. `manage` is a command-line tool to manage the server. It can automatically start, stop, and restart your instance. @@ -51,9 +108,14 @@ chmod +x manage ``` After doing that, you are now ready to use the script. -# Common `manage` commands -+ **Start Server:** `./manage up` -+ **Stop Server:** `./manage down` -+ **Restart Server:** `./manage restart` -+ **Server Status:** `./manage --status` -+ **Help:** `./manage help` +Usage: `./manage [command] [options]` + +## `manage` commands ++ `./manage up` - Builds the project and starts the server. ++ `./manage down` - Stops the server. ++ `./manage restart` - Restarts the server. ++ `./manage status, -s, --status` - Checks if the server is running. ++ `./manage help, -h, --help` - Shows the help message. + +## `manage` options ++ `--db-alive` - Do not restart Docker services (database). \ No newline at end of file