diff --git a/docs/1-intro.md b/docs/1-overview.md similarity index 99% rename from docs/1-intro.md rename to docs/1-overview.md index 9a0209d..f645d86 100644 --- a/docs/1-intro.md +++ b/docs/1-overview.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# Intro +# Overview :::warning **UNDER DEVELOPMENT. Not even pre-alpha** diff --git a/docs/4-api/1-overview.md b/docs/4-api/1-overview.md deleted file mode 100644 index 11c1aab..0000000 --- a/docs/4-api/1-overview.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Overview - -Firebase http API for the [llama bot](https://github.com/llama-bot/llama-bot). - -## Endpoints - -### Auhentication - -#### `/login` - -Login using discord OAuth2 - -#### `/logout` - -Logout from account - -#### `/auth` - -Discord OAuth2 callback - -### REST - -#### `/user-data` - -List all servers in the database - -## Special thanks - -- [luizkc](https://github.com/luizkc) for discord oauth2 authentication ([repo](https://github.com/luizkc/firebase-discord-oauth2-example)) diff --git a/docs/4-api/2-setting-up.md b/docs/4-api/2-setting-up.md deleted file mode 100644 index 2e67422..0000000 --- a/docs/4-api/2-setting-up.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Setting up - -This page will teach you how to set up the [Llama bot web API](https://github.com/llama-bot/llama-bot-web-api). - -## Steps - -### Pre-requirements - -- [Node.js](https://nodejs.org) version 14 or greater -- Discord account -- Google Firebase account - -### Discord - -1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create an application. Select one if you already have it. Using the same application used by the discord bot is recommended. -2. Go to the OAuth2 tab. -3. Add the following redirect URIs: - - - localhost for testing (http only): `http://localhost:5001//us-central1/api/auth` - - http: `http://us-central1-.cloudfunctions.net/api/auth` - - https: `https://us-central1-.cloudfunctions.net/api/auth` - -### Firebase - -- must be the same project that the llama bot is using - -1. Create a firebase project. - - https://console.firebase.google.com - -2. Create/Select a project. Make sure it is using the [blaze plan](https://firebase.google.com/pricing). -3. Go to the `Firestore Database` tab and enable it (using production mode is highly recommended). - -### Local - -1. Clone the [llama-bot-web-api](https://github.com/llama-bot/llama-bot-web-api) repository - - Using HTTPS - - ```bash - git clone https://github.com/llama-bot/llama-bot-web-api.git - ``` - - Using SSH: - - ```bash - git clone git@github.com:llama-bot/llama-bot-web-api.git - ``` - -2. Edit `functions/src/config.json`. - - ```json title="functions/src/config.json" - { - "region": "FIREBASE_FUNCTIONS_REGION_HERE", // Region where firebase functions is hosted in. Example: us-central1 - "scopes": ["DISCORD", "SCOPES", "HERE"] // Discord OAuth2 scopes. Example: ["identify", "email", "guilds"] - } - ``` - -3. Create `functions/src/secret.json` and fill in the data. - - ```json title="functions/src/secret.json" - { - "projectID": "FIREBASE_PROJECT_ID_HERE", // Firebase project ID - "clientID": "DISCORD_CLIENT_ID_HERE", // Discord OAuth2 Client ID - "clientSecret": "DISCORD_CLIENT_SECRET_HERE", // Discord OAuth2 Client Secret - "secret": "SECRET_COOKIE_KEY_HERE" // secret to be used for express session - } - ``` - -4. Go to [this link](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk), select your firebase project and download the firebase admin sdk key by pressing the "Generate new private key" button. Rename it to `firebase-adminsdk.json` and put it in `functions/src/`. - -5. Install firebase cli tools. - - ```bash - npm install -g firebase-tools - ``` - -6. Select firebase project - - ```bash - firebase use - ``` - -7. Go to `functions` directory and install necessary dependencies. - - ```bash - npm install - ``` - -## Testing - -1. Start local test server by running the following command in the `functions` directory. - - ```bash - npm run serve - ``` - -2. Open locally served API and log in with your discord account. - - :::warning - HTTP**S** won't work when serving locally. Use HTTP instead. - ::: - - Login test URI: `http://localhost:5001//us-central1/api/login` - -3. If everything is set up correctly, this should have added a new user in firestore database. - -### Deploying - -Deploying the functions to production is as simple as running the following command: - -```bash -firebase deploy -``` - -Production API URL: `https://us-central1-.cloudfunctions.net/api`. - -## More info - -- discord developers documentation: https://discord.com/developers/docs -- firebase admin sdk documentation: https://firebase.google.com/docs diff --git a/docs/4-api/_category_.json b/docs/4-api/_category_.json deleted file mode 100644 index 97ae9c2..0000000 --- a/docs/4-api/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "API", - "position": 4 -} diff --git a/docs/4-web-interface/1-overview.md b/docs/4-web-interface/1-overview.md new file mode 100644 index 0000000..f84e6ab --- /dev/null +++ b/docs/4-web-interface/1-overview.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 1 +--- + +# Overview + +A full stack web graphical user interface for the [llama bot](https://github.com/llama-bot/llama-bot). + +## Special thanks + +- [luizkc](https://github.com/luizkc) for discord oauth2 authentication ([repo](https://github.com/luizkc/firebase-discord-oauth2-example)) +- [charfweh](https://github.com/charfweh) for a full stack discord login example ([repo](https://github.com/charfweh/Discord-Oauth-Mern)) diff --git a/docs/4-web-interface/2-setting-up.md b/docs/4-web-interface/2-setting-up.md new file mode 100644 index 0000000..15d1659 --- /dev/null +++ b/docs/4-web-interface/2-setting-up.md @@ -0,0 +1,160 @@ +--- +sidebar_position: 2 +--- + +# Setting up + +This page will teach you how to set up the [Llama bot web Interface](https://github.com/llama-bot/llama-bot-web-interface). + +## Pre-requirements + +- [Node.js](https://nodejs.org) version 14 or greater +- npm & yarn (npm is included in node.js) +- Discord account +- Google Firebase account +- Payment method (No payment required for light usage. More info [here](https://firebase.google.com/pricing)) + +## Discord + +1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create an application. Select one if you already have it. Using the same application used by the discord bot is recommended. +2. Go to the OAuth2 tab. +3. Add the following redirects: + + - testing (http): `http://localhost:5000/api/auth` + - production (https): `https:///api/auth` (example: `https://llama.developomp.com/api/auth`) + +## Firebase + +1. Create a firebase project. Select one if you already have it. Using the same project usd by the bot is recommended. Make sure it is using the [blaze plan](https://firebase.google.com/pricing) + + https://console.firebase.google.com + +2. Go to the `Firestore Database` tab and enable it. Using production mode is highly recommended. + +## Local + +Clone the [llama-bot-web-interface](https://github.com/llama-bot/llama-bot-web-interface) repository + +Using HTTPS + +```bash +git clone https://github.com/llama-bot/llama-bot-web-interface.git +``` + +Using SSH: + +```bash +git clone git@github.com:llama-bot/llama-bot-web-interface.git +``` + +## Functions + +1. Edit `functions/src/config.json`. + + ```json title="functions/src/config.json (default values)" + { + "pathPrefix": "/api", // where the API endpoints will be located. Set it to "/" if it's on another domain (example: api.example.com) + "scopes": ["identify", "email", "guilds"] // Discord OAuth2 scopes. + } + ``` + + more info about discord OAuth2 scopes can be found in the [discord developers documentation](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes) + +2. Create `functions/src/secret.json` and fill in the data. + + ```json title="functions/src/secret.json" + { + "clientID": "DISCORD_CLIENT_ID_HERE", // Discord OAuth2 Client ID + "clientSecret": "DISCORD_CLIENT_SECRET_HERE", // Discord OAuth2 Client Secret + "secret": "SECRET_COOKIE_KEY_HERE" // secret key to be used for express session security + } + ``` + +3. Go to [this link](https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk), select your firebase project and download the firebase admin sdk key by pressing the "Generate new private key" button. Rename it to `firebase-adminsdk.json` and put it in `functions/src/`. This is necessary for firebase firestore database access. + +4. Install firebase cli tools. + + ```bash + npm install -g firebase-tools + ``` + +5. Select firebase project + + ```bash + firebase use + ``` + +6. Go to `functions` directory and install necessary dependencies. + + ```bash + npm install + ``` + +7. Build production code. + + ```bash + npm run build + ``` + +## Frontend + +1. Go to `frontend` directory and install dependencies. + + ```bash + yarn install + ``` + +2. Build site for production. + + ```bash + yarn build + ``` + +## Testing + +:::info +Build backend and frontend code first +::: + +1. Start local test server by running the following command: + + ```bash + firebase serve + ``` + +2. Open locally served test site and log in with your discord account. + + [http://localhost:5000](http://localhost:5000) + +3. If everything is set up correctly, this should have added a new user in firestore database. + +## Deployment + +:::warning +Make sure to test your code before deploying to production +::: + +Deploying the code to production is as simple as running the following command: + +```bash +firebase deploy +``` + +The deployment could take a while so be patient. + +To deploy frontend code only: + +```bash +firebase deploy --only hosting +``` + +To deploy backend code only: + +```bash +firebase deploy --only functions +``` + +## More info + +- discord developers documentation: https://discord.com/developers/docs +- firebase admin sdk documentation: https://firebase.google.com/docs diff --git a/docs/4-web-interface/3-api.md b/docs/4-web-interface/3-api.md new file mode 100644 index 0000000..98036ec --- /dev/null +++ b/docs/4-web-interface/3-api.md @@ -0,0 +1,27 @@ +--- +sidebar_position: 3 +--- + +# API + +HTTP endpoints. + +## Authentication + +### `/api/login` + +Login using discord OAuth2 + +### `/api/logout` + +Logout from account + +### `/api/auth` + +Discord OAuth2 callback + +## Data + +### `/api/user-data` + +Basic data about the user diff --git a/docs/5-web-interface/_category_.json b/docs/4-web-interface/_category_.json similarity index 66% rename from docs/5-web-interface/_category_.json rename to docs/4-web-interface/_category_.json index 5ad17f5..8b17e02 100644 --- a/docs/5-web-interface/_category_.json +++ b/docs/4-web-interface/_category_.json @@ -1,4 +1,4 @@ { "label": "Web Interface", - "position": 5 + "position": 4 } diff --git a/docs/5-web-interface/1-overview.md b/docs/5-web-interface/1-overview.md deleted file mode 100644 index 5bc6931..0000000 --- a/docs/5-web-interface/1-overview.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Overview