getting started documentation

README.md

@@ -1,87 +1,61 @@
-<p align="center">
-  <img src="https://github.com/mk6i/retro-aim-server/assets/2894330/adff6b45-fcae-400c-8876-52e891a36ee0" width="300">
-</p>
+# Retro AIM Server
+
+**Retro AIM Server** is an open source AOL Instant Messenger server that supports classic AIM clients from the 2000s.
+Bootstrap your own instant messaging network with minimal setup!
 
 <p align="center">
-  <a href="https://codecov.io/github/mk6i/retro-aim-server">
-    <img src="https://codecov.io/github/mk6i/retro-aim-server/graph/badge.svg?token=MATKPP77JT" alt="codecov">
-  </a>
+  <img width="616" alt="screenshot of retro aim server running next to AIM" src="https://github.com/mk6i/retro-aim-server/assets/2894330/81ff419f-50fa-4961-bd2f-ac7dcac903b5">
 </p>
 
-Retro AIM Server is a server implementation of the OSCAR protocol that supports AIM versions 5.0-5.9.
-
-This project is currently under heavy development. Retro AIM Server supports/will support the following features:
+The following features are supported:
 
-- [x] Instant Messaging
-- [x] Buddy List
-- [x] Warning
+- [x] Windows AIM client versions 5.0-5.9 (partial 4.8 support)
 - [x] Away Messages
-- [x] User Profiles
-- [x] Chat Rooms
-- [x] Visibility Toggle
-- [x] User Blocking
 - [x] Buddy Icons
-- [ ] User Directory
-
-## Quickstart
-
-### Dependencies
-
-A C compiler is required in order to build the sqlite dependency.
-
-**MacOS**
-
-> If you have git, this is likely already set up on your machine.
-
-```shell
-xcode-select --install
-```
-
-**Linux (Ubuntu)**
-
-```shell
-sudo apt install build-essential
-```
-
-Retro AIM Server requires [go 1.21](https://go.dev/) or newer to run.
-
-### Run the Server
-
-Start Retro AIM Server with the following command. The default settings can be modified in `config/settings.env`.
+- [x] Buddy List
+- [x] Chat Rooms
+- [x] Instant Messaging
+- [x] User Profiles
+- [x] Blocking / Visibility Toggle / Idle Notification
+- [x] Warning
 
-```shell
-scripts/run_dev.sh
-```
+## 🏁 How to Run
 
-### Configure AIM Client
+Get up and running with Retro AIM Server using one of these handy quickstart guides:
 
-Download Windows AIM ([v5.1.3036 recommended](https://archive.org/details/aim513036)) and install on Windows 10/11 using
-[Windows XP compatibility mode](https://support.microsoft.com/en-us/windows/make-older-apps-or-programs-compatible-with-windows-783d6dd7-b439-bdb0-0490-54eea0f45938)
-or MacOS/Linux via [Wine](https://www.winehq.org/). 
+* [Linux (x86_64)](./docs/LINUX.md)
+* [macOS (Intel and Apple Silicon)](./docs/MACOS.md)
+* [Windows 10/11 (x86_64)](./docs/WINDOWS.md)
 
-Once installed, configure the AIM client to connect to Retro AIM Server as
-follows:
+## 🛠️ Development
 
-1. At the sign-on screen, click `Setup`.
-2. Under the `Sign On/Off` category, click `Connection`.
-3. In the `Server  > Host` field, enter the value of `OSCAR_HOST` found in `config/settings.env`.
-4. In the `Server > Port` field, enter the value of `BOS_PORT` found in `config/settings.env`.
+This project is under active development. Contributions are welcome!
 
-Apply the settings and sign on to AIM. By default, you can sign on with any screen name/password without first
-registering (see `DISABLE_AUTH` in `config/settings.env` for more details).
+Follow [this guide](./docs/BUILD.md) to learn how to compile and run Retro AIM Server.
 
-### User Management
+## 👤 User Management
 
-User management is done through a REST API.
+Accounts can be added via the User Management API (see [OpenAPI spec](./api.yml)):
 
-#### List Users
+### List Users
 
 ```curl
 curl http://localhost:8080/user
 ```
 
-#### Create Users
+### Create Users
 
 ```curl
 curl -d'{"screen_name":"myScreenName", "password":"thepassword"}' http://localhost:8080/user
 ```
+
+## 🔗 Acknowledgements
+
+- [aim-oscar-server](https://github.com/ox/aim-oscar-server) is another cool open source AIM server project.
+- [NINA Wiki](https://wiki.nina.chat/wiki/Main_Page) is an indispensable source for figuring out the OSCAR API.
+- [libpurple](https://developer.pidgin.im/wiki/WhatIsLibpurple) is also an invaluable OSCAR reference (especially
+  version [2.10.6-1](https://github.com/Tasssadar/libpurple)).
+
+## 📄 License
+
+Retro AIM Server is licensed under the [MIT license](./LICENSE).

docs/BUILD.md

@@ -0,0 +1,45 @@
+# Development: How to Run/Compile Retro AIM Server
+
+This document explains how to Build Retro AIM Server.
+
+## Dependencies
+
+A C compiler is required in order to build the sqlite dependency.
+
+**macOS**
+
+> If you have git, this is likely already set up on your machine.
+
+```shell
+xcode-select --install
+```
+
+**Linux (Ubuntu)**
+
+```shell
+sudo apt install build-essential
+```
+
+Retro AIM Server requires [go 1.21](https://go.dev/) or newer to run.
+
+## Run the Server
+
+To run Retro AIM Server without building a binary, run the following script. The default settings can be modified
+in `config/settings.env`.
+
+```shell
+scripts/run_dev.sh
+```
+
+## Build the Server
+
+```shell
+go build -o retro_aim_server ./cmd/server
+```
+
+To run:
+
+```shell
+source config/settings.env
+./retro_aim_server
+```

docs/CLIENT.md

@@ -0,0 +1,18 @@
+# AIM Client Configuration
+
+This guide explains how to configure a Windows AIM clients to connect to Retro AIM Server.
+
+1. At the sign-on screen, click `Setup`.
+   <p>
+      <img width="319" alt="screenshot of AIM sign-on screen" src="https://github.com/mk6i/mkdb/assets/2894330/9e0e743e-e41d-4c45-9e82-d97d7d4325f3">
+   </p>
+2. Under the `Sign On/Off` category, click `Connection`.
+   <p>
+      <img width="662" alt="screenshot of AIM preferences window" src="https://github.com/mk6i/mkdb/assets/2894330/c7cfcaa4-8132-4b57-b5c9-7643c99cbda2">
+   </p>
+3. In the `Host` field, enter the value of `OSCAR_HOST` found in `config/settings`. In the `Port` field, enter the
+   value of `BOS_PORT` found in `config/settings`.
+   <p>
+      <img width="618" alt="Screen Shot 2024-03-29 at 11 22 19 PM" src="https://github.com/mk6i/mkdb/assets/2894330/da17c457-a773-4b82-b4ba-cb81f9a2e085">
+   </p>
+4. Click OK and sign in to AIM!

docs/LINUX.md

@@ -0,0 +1,40 @@
+# Retro AIM Server Quickstart for Linux (x86_64)
+
+This guide explains how to download, configure and run Retro AIM Server on Linux (x86_64).
+
+1. **Download Retro AIM Server**
+
+   Grab the latest Linux release from the [releases page](https://github.com/mk6i/retro-aim-server/releases) and extract
+   the archive. The extracted folder contains the application and a configuration file `settings.env`.
+
+2. **Configure Server Address**
+
+   Set `OSCAR_HOST` in `settings.env` to a hostname that AIM clients can connect to. The default setting is `127.0.0.1`,
+   which is enough to connect clients on the same PC.
+
+   In order to connect AIM clients on your LAN (including VMs with bridged networking), you can find the appropriate IP
+   address by running `ifconfig` from the terminal
+
+3. **Start the Application**
+
+   Run the following command to launch Retro AIM Server:
+
+   ```shell
+   ./retro_aim_server
+   ```
+
+   Retro AIM Server will run in the terminal, ready to accept AIM client connections.
+
+4. **Configure AIM Clients**
+
+   To do a quick sanity check, start an AIM client, sign in to the server, and send yourself an instant message.
+   Configure the AIM client to connect to the host set in `OSCAR_HOST` in `settings.env`. (If you didn't change the
+   config, the address is `127.0.0.1`.)
+
+   See the [Client Configuration Guide](./CLIENT.md) for more detail on setting up the AIM client.
+
+   By default, you can enter *any* screen name and password at the AIM sign-in screen to auto-create an account.
+
+   > 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.bat` to enforce account authentication. User accounts can be created via
+   the [User Management API](../README.md#user-management).

docs/MACOS.md

@@ -0,0 +1,76 @@
+# Retro AIM Server Quickstart for macOS (Intel and Apple Silicon)
+
+This guide explains how to download, configure and run Retro AIM Server on macOS (Intel and Apple Silicon).
+
+1. **Download Retro AIM Server**
+
+   Grab the latest macOS release from the [Releases page](https://github.com/mk6i/retro-aim-server/releases).
+
+   Because the Retro AIM Server `.app` has not been blessed by Apple, browsers such as Chrome may think it's a
+   "suspicious" file and block the download, in which case you need to explicitly opt in to downloading the untrusted
+   file.
+
+    <p align="center">
+      <img alt="screenshot of a chrome prompt showing a blocked download" src="https://github.com/mk6i/retro-aim-server/assets/2894330/90af40bd-262d-4e0f-a769-06943c7acd18">
+    </p>
+
+   > While the binaries are 100% safe, you can avoid the security concern by [building the application yourself](./BUILD.md).
+   We do not provide signed binaries because of the undue cost and complexity.
+
+   Once downloaded, extract the `.zip` archive, which contains the application and a configuration file `settings.bat`.
+
+2. **Open Terminal**
+
+   Open a terminal and navigate to the extracted directory. This terminal will be used for the remaining steps.
+
+   ```shell
+   cd ~/Downloads/retro_aim_server.0.1.0.macos.intel_x86_64/
+   ```
+
+3. **Remove Quarantine**
+
+   Because the Retro AIM Server `.app` has not been blessed by Apple, macOS will quarantine the application. To proceed,
+   remove the quarantine flag from the `.app`. In the same terminal, run following command:
+
+   ```shell
+   sudo xattr -d ./retro-aim-server
+   ```
+
+   > While the binaries are 100% safe, you can avoid the security concern by [building the application yourself](./BUILD.md).
+   We do not provide signed binaries because of the undue cost and complexity.
+
+4. **Configure Server Address**
+
+   Set `OSCAR_HOST` in `settings.env` to a hostname that AIM clients can connect to. The default setting is `127.0.0.1`,
+   which is enough to connect clients on the same machine.
+
+   In order to connect AIM clients on your LAN (including VMs with bridged networking), you can find the appropriate IP
+   address by running the following command in the terminal:
+
+   ```shell
+   osascript -e "IPv4 address of (system info)"
+   ```
+
+5. **Start the Application**
+
+   Run the following command to launch Retro AIM Server:
+
+   ```shell
+   ./retro_aim_server
+   ```
+
+   Retro AIM Server will run in the terminal, ready to accept AIM client connections.
+
+6. **Test**
+
+   To do a quick sanity check, start an AIM client, sign in to the server, and send yourself an instant message.
+   Configure the AIM client to connect to the host set in `OSCAR_HOST` in `settings.env`. (If you didn't change the
+   config, the address is `127.0.0.1`.)
+
+   See the [Client Configuration Guide](./CLIENT.md) for more detail on setting up the AIM client.
+
+   By default, you can enter *any* screen name and password at the AIM sign-in screen to auto-create an account.
+
+   > 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 [User Management API](../README.md#user-management).

docs/RELEASE.md

@@ -1,4 +1,4 @@
-# Releasing
+# Retro AIM Server Release Process
 
 This document explains how the Retro AIM Server release process works.
 
@@ -73,4 +73,8 @@ The following is the procedure that builds Retro AIM Server and uploads the buil
 5. **Release It!**
 
    Now run the release process. Once its complete, a new [release](https://github.com/mk6i/retro-aim-server/releases)
-   should appear in Github with download artifacts attached.
+   should appear in Github with download artifacts attached.
+
+    ```shell
+   make release
+    ```

docs/WINDOWS.md

@@ -0,0 +1,62 @@
+# Retro AIM Server Quickstart for Windows 10/11
+
+This guide explains how to download, configure and run Retro AIM Server on Windows 10/11.
+
+1. **Download Retro AIM Server**
+
+   Grab the latest Windows release from the [Releases page](https://github.com/mk6i/retro-aim-server/releases).
+
+   Because the Retro AIM Server `.exe` has not been blessed by Microsoft, browsers such as Chrome may think it's a
+   "suspicious" file and block the download, in which case you need to explicitly opt in to downloading the untrusted
+   file.
+
+    <p align="center">
+      <img alt="screenshot of a chrome prompt showing a blocked download" src="https://github.com/mk6i/retro-aim-server/assets/2894330/6bf2fd79-0a42-48b2-a695-d777259a3603">
+    </p>
+
+   > While the binaries are 100% safe, you can avoid the security concern by [building the application yourself](./BUILD.md).
+   We do not provide signed binaries because of the undue cost and complexity.
+
+   Once downloaded, extract the `.zip` archive, which contains the application and a configuration file `settings.bat`.
+
+2. **Configure Server Address**
+
+   Set `OSCAR_HOST` in `settings.bat` to a hostname that AIM clients can connect to. The default setting is `127.0.0.1`,
+   which is enough to connect clients on the same PC.
+
+   In order to connect AIM clients on your LAN (including VMs with bridged networking), you can find the appropriate IP
+   address by running `ipconfig` from the Command Prompt.
+
+3. **Start the Application**
+
+   Open `run.cmd` to launch Retro AIM Server.
+
+   Because Retro AIM Server has not been blessed by Microsoft, Windows will flag the application as a security risk the
+   first time you run it. You'll be presented with a `Microsoft Defender SmartScreen` warning prompt that gives you the
+   option to run the blocked application.
+
+   To proceed, click `More Options`, then `Run anyway`.
+
+    <p align="center">
+      <img alt="of screenshot microsoft defender smartscreen prompt" src="https://github.com/mk6i/retro-aim-server/assets/2894330/9ab0966b-d5dd-4b70-ba16-483e5c458f89">
+      <img alt="of screenshot microsoft defender smartscreen prompt" src="https://github.com/mk6i/retro-aim-server/assets/2894330/5d4106c6-0ce6-4d4f-9260-e9bbb777c770">
+    </p>
+
+   > While the binaries are 100% safe, you can avoid the security concern by [building the application yourself](./BUILD.md).
+   We do not provide signed binaries because of the undue cost and complexity.
+
+   Retro AIM Server will open in a Command Prompt, ready to accept AIM client connections.
+
+4. **Test**
+
+   To do a quick sanity check, start an AIM client, sign in to the server, and send yourself an instant message.
+   Configure the AIM client to connect to the host set in `OSCAR_HOST` in `settings.bat`. (If you didn't change the
+   config, the address is `127.0.0.1`.)
+
+   See the [Client Configuration Guide](./CLIENT.md) for more detail on setting up the AIM client.
+
+   By default, you can enter *any* screen name and password at the AIM sign-in screen to auto-create an account.
+
+   > 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.bat` to enforce account authentication. User accounts can be created via
+   the [User Management API](../README.md#user-management).