kawari/USAGE.md

# Usage

Kawari is designed to be easy to run, with the goal of being accessible to anyone who wants to run a local server for themselves.

**Note:** Persisted data (logins, characters, etc) is _not_ stable or secure. Treat all data as disposable.

## Copyright Notice

**Kawari requires that you have an active subscription**, and are in possession of a legitimate copy of the game. Kawari is not related or affiliated to SqEx, and by using it you are in explicit violation of the User Agreement (_Limitation 2.4_.)

## Prerequisites
* Linux
* Copy of the game updated to the supported game version (see README)
* Oodle Network Compression (can be obtained from [here](https://github.com/WorkingRobot/OodleUE), place static library (`.a`) into `oodle` directory)

## Setup

Build Kawari with `cargo build`. Then run it with the helper script:

```shell
$ ./run.sh
```

## Reverse proxy setup

Kawari is useless if it's not behind a domain or other address accessible to a launcher. Even something like Caddy is good enough, and we provide an example setup in the root of the repository.

```shell
$ caddy run
```

This Caddyfile hosts several domains, most notably `ffxiv.localhost`, on port 80. If you get a "permission denied" error starting Caddy, you must either start Caddy with elevated privileges or set the `CAP_NET_BIND_SERVICE` capability. See [here](https://caddyserver.com/docs/quick-starts/caddyfile) for more information on how to do this.

## Logging in

[Astra](https://github.com/redstrate/Astra) is the only launcher known to work, and it requires compiling the unreleased master branch. **If you don't know what any of that means, then wait for a new release of Astra before trying Kawari.**

1. Enable "Developer Settings" under "General".
2. Under "Developer Settings", enter the addresses of your servers in the section indicated below. If you used the default Caddy setup, tapping the "Set to localhost" button will fill these fields for you with the correct addresses.
3. In "Game Server" and "Game Server Port", set it to "127.0.0.1" and "7000" respectively. This is the address and port of your **Lobby** server.

Any username and password combination will work, as there is no actual login database yet. In the client, make sure to select the **Aether data center**.
Add a basic login system This allows you to register in the web frontend now, and the login server now checks this before giving a session ID. Note that this is wildly insecure (it stores the passwords in plaintext!) and is duly noted in the USAGE. 2025-03-16 20:55:51 -04:00			`# Usage`
Update documentation 2025-03-14 17:00:40 -04:00
			`Kawari is designed to be easy to run, with the goal of being accessible to anyone who wants to run a local server for themselves.`

Add a basic login system This allows you to register in the web frontend now, and the login server now checks this before giving a session ID. Note that this is wildly insecure (it stores the passwords in plaintext!) and is duly noted in the USAGE. 2025-03-16 20:55:51 -04:00			`Note: Persisted data (logins, characters, etc) is _not_ stable or secure. Treat all data as disposable.`

Update documentation 2025-03-14 17:00:40 -04:00			`## Copyright Notice`

			`Kawari requires that you have an active subscription, and are in possession of a legitimate copy of the game. Kawari is not related or affiliated to SqEx, and by using it you are in explicit violation of the User Agreement (_Limitation 2.4_.)`

			`## Prerequisites`
			`* Linux`
			`* Copy of the game updated to the supported game version (see README)`
Clarify Oodle instructions, link against "oodle" directory While you can just drop the Oodle static library into /usr, I'm not a big fan of doing it, especially when the binary didn't come from my machine or package manager. You can set a RUSTFLAGS environment variable or cargo config file to specify a link path, but having the build script search there for you is easier. The docs now specify which variant of Oodle is required, since there are multiple. It also specifically mentions the static library, because I had some weird issues leaving the dynamic library in that folder, where the executables wouldn't start unless it could dynamically load the .so. 2025-03-17 14:08:51 -04:00			* Oodle Network Compression (can be obtained from [here](https://github.com/WorkingRobot/OodleUE), place static library (`.a`) into `oodle` directory)
Update documentation 2025-03-14 17:00:40 -04:00
			`## Setup`

			Build Kawari with `cargo build`. Then run it with the helper script:

			```shell
			`$ ./run.sh`
			```

			`## Reverse proxy setup`

			`Kawari is useless if it's not behind a domain or other address accessible to a launcher. Even something like Caddy is good enough, and we provide an example setup in the root of the repository.`

			```shell
Document magic domains, privileged port usage I ran into the issue with privileged ports myself. The link to the Caddy website has an aside about how to use setcap or sudo, which should be good enough. 2025-03-17 14:27:53 -04:00			`$ caddy run`
Update documentation 2025-03-14 17:00:40 -04:00			```

Document magic domains, privileged port usage I ran into the issue with privileged ports myself. The link to the Caddy website has an aside about how to use setcap or sudo, which should be good enough. 2025-03-17 14:27:53 -04:00			This Caddyfile hosts several domains, most notably `ffxiv.localhost`, on port 80. If you get a "permission denied" error starting Caddy, you must either start Caddy with elevated privileges or set the `CAP_NET_BIND_SERVICE` capability. See [here](https://caddyserver.com/docs/quick-starts/caddyfile) for more information on how to do this.

Update documentation 2025-03-14 17:00:40 -04:00			`## Logging in`

			`[Astra](https://github.com/redstrate/Astra) is the only launcher known to work, and it requires compiling the unreleased master branch. If you don't know what any of that means, then wait for a new release of Astra before trying Kawari.`

			`1. Enable "Developer Settings" under "General".`
			`2. Under "Developer Settings", enter the addresses of your servers in the section indicated below. If you used the default Caddy setup, tapping the "Set to localhost" button will fill these fields for you with the correct addresses.`
			`3. In "Game Server" and "Game Server Port", set it to "127.0.0.1" and "7000" respectively. This is the address and port of your Lobby server.`

			`Any username and password combination will work, as there is no actual login database yet. In the client, make sure to select the Aether data center.`