From c5bdd2c41d8b3995b54ba95cfcd28a18a6786fd2 Mon Sep 17 00:00:00 2001 From: Mike Date: Sun, 22 Sep 2024 23:16:05 -0400 Subject: [PATCH] document keyword setup --- config/settings.env | 2 +- docs/ADDITIONAL_SETUP.md | 77 ++++++++++++++++++++++++++++++++++++++++ docs/LINUX.md | 7 +++- docs/MACOS.md | 7 +++- docs/WINDOWS.md | 5 +++ 5 files changed, 95 insertions(+), 3 deletions(-) create mode 100644 docs/ADDITIONAL_SETUP.md diff --git a/config/settings.env b/config/settings.env index c7a61897..3226833f 100644 --- a/config/settings.env +++ b/config/settings.env @@ -52,5 +52,5 @@ export LOG_LEVEL=info # clients, a private IP address (e.g. 192.168..) or hostname should suffice. For # clients connecting over the Internet, specify your public IP address and # ensure that TCP ports 5190-5197 are open on your firewall. -export OSCAR_HOST=127.0.0.1 +export OSCAR_HOST=192.168.68.59 diff --git a/docs/ADDITIONAL_SETUP.md b/docs/ADDITIONAL_SETUP.md new file mode 100644 index 00000000..fd11dcff --- /dev/null +++ b/docs/ADDITIONAL_SETUP.md @@ -0,0 +1,77 @@ +# Additional Setup + +This guide covers some optional configuration steps to get the best experience from Retro AIM Server. + +## Configure User Directory Keywords + +AIM users can make themselves searchable by interest in the user directory by configuring up to 5 interest keywords. The +keywords are organized by category. + +Retro AIM Server does not come with any keywords installed out of the box. The following steps explain how to add +keywords and keyword categories via the management API. + +1. **Add Keyword Categories** + + The following requests add 3 keyword categories: + + ```shell + curl -d'{"name": "Programming Languages"}' http://localhost:8080/directory/category + curl -d'{"name": "Books"}' http://localhost:8080/directory/category + curl -d'{"name": "Music"}' http://localhost:8080/directory/category + ``` + + The following request lists all keyword categories along with their IDs, which are required for associating keywords + to categories. + + ```shell + curl http://localhost:8080/directory/category + ``` + + This output shows the categories and their corresponding IDs, which you will use to assign keywords in the next step. + + ```json + [ + { + "id": 2, + "name": "Books" + }, + { + "id": 3, + "name": "Music" + }, + { + "id": 1, + "name": "Programming Languages" + } + ] + ``` + +2. **Add Keywords** + + Two types of keywords are supported: categorized keywords, which belong to a specific category (e.g., Books, Music), + and top-level keywords, which appear at the top of the menu and are not associated with any category. + + The following request sets up 3 keywords for books, music, and programming languages categories, respectively. + + ```shell + curl -d'{"category_id": 2, "name": "The Dictionary"}' http://localhost:8080/directory/keyword + curl -d'{"category_id": 3, "name": "Rock"}' http://localhost:8080/directory/keyword + curl -d'{"category_id": 1, "name": "golang"}' http://localhost:8080/directory/keyword + ``` + + This request adds a single top-level keyword. + + ```shell + curl -d'{"name": "Live, laugh, love!"}' http://localhost:8080/directory/keyword + ``` + + Fully rendered, the keyword list looks like this in the AIN client: + +

+ screenshot of AIM interests keywords menu +

+ +3. **Restart** + + After creating or modifying keyword categories and keywords, users currently connected to the server must sign out + and back in again in order to see the updated keyword list. \ No newline at end of file diff --git a/docs/LINUX.md b/docs/LINUX.md index 349909af..923603d2 100644 --- a/docs/LINUX.md +++ b/docs/LINUX.md @@ -37,4 +37,9 @@ This guide explains how to download, configure and run Retro AIM Server on Linux > Account auto-creation is meant to be a convenience feature for local development. In a production deployment, you should set `DISABLE_AUTH=false` in `settings.env` to enforce account authentication. User accounts can be created via - the [Management API](../README.md#-management-api). \ No newline at end of file + the [Management API](../README.md#-management-api). + +5. **Additional Setup** + + For optional configuration steps that enhance your Retro AIM Server experience, refer to + the [Additional Setup Guide](./ADDITIONAL_SETUP.md). \ No newline at end of file diff --git a/docs/MACOS.md b/docs/MACOS.md index c7ffaf68..9d2fe25b 100644 --- a/docs/MACOS.md +++ b/docs/MACOS.md @@ -74,4 +74,9 @@ This guide explains how to download, configure and run Retro AIM Server on macOS > Account auto-creation is meant to be a convenience feature for local development. In a production deployment, you should set `DISABLE_AUTH=false` in `settings.env` to enforce account authentication. User accounts can be created via - the [Management API](../README.md#-management-api). \ No newline at end of file + the [Management API](../README.md#-management-api). + +7. **Additional Setup** + + For optional configuration steps that enhance your Retro AIM Server experience, refer to + the [Additional Setup Guide](./ADDITIONAL_SETUP.md). \ No newline at end of file diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index 8dd5d2a9..0ce1c2c2 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -51,3 +51,8 @@ This guide explains how to download, configure and run Retro AIM Server on Windo > Account auto-creation is meant to be a convenience feature for local development. In a production deployment, you should set `DISABLE_AUTH=false` in `settings.env` to enforce account authentication. User accounts can be created via the [Management API](../README.md#-management-api). + +5. **Additional Setup** + + For optional configuration steps that enhance your Retro AIM Server experience, refer to + the [Additional Setup Guide](./ADDITIONAL_SETUP.md). \ No newline at end of file