From 12365e5ce71331e46a5d80b3a5cc835b3d034c07 Mon Sep 17 00:00:00 2001 From: myst Date: Tue, 13 Aug 2024 03:57:36 +0200 Subject: [PATCH] feat(infrastructure): adjust readme.md - removed CONTRIBUTING.md --- CONTRIBUTING.md | 15 -- README.md | 178 ++++++++++++++++-- .../environment/types/environment-keys.ts | 14 +- 3 files changed, 166 insertions(+), 41 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index be03a888..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,15 +0,0 @@ -# Contributing - -## Issue/Enhancement Review -Please provide new ideas and comments in the Issue-List. - -## Change Size -When you have only a few changes you may use the comments in the appropriate issue for providing the correction. -Example: additional muds in the mudlist in ./frontend/config/config.development - -For multiple file changes please fork the project, do, test and commit the changes prior to an pull request. - -## Contact: -- Issuelist in this project. -- Contact myonara within the mud UNItopia. e.g. via https://unitopia.de/webmud2beta#locked -- Talking with each other can help a lot :-) diff --git a/README.md b/README.md index 9b82d035..3c87ee34 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,168 @@ -# webmud3 V0.5.0 +# webmud3 1.0.0 Alpha -Webmud3: third generation of the UNItopia Webmud as open source project. +[![Build and Test](https://github.com/unitopia-de/webmud3/actions/workflows/build_and_test.yml/badge.svg?branch=develop)](https://github.com/unitopia-de/webmud3/actions/workflows/build_and_test.yml) -Is up and running: -* https://www.unitopia.de/webmud3/ -* https://seifenblase.de/webmud3/ +Webmud3: third generation of the [UNItopia](https://www.unitopia.de) Webmud as open source project. -With Version 0.5.0 all dockerfiles were condensed into one 'latest' image. +Webmud3 is a modern MUD (Multi-User Dungeon) client that consists of a NodeJS-based backend and a web-based frontend. +This client provides comprehensive support for Telnet and the protocols built on top of it, such as GMCP (Generic Mud Communication Protocol) and MXP (Mud eXtension Protocol), specifically designed for interaction with MUD servers. +## Features -For own testing please use the following docker command to create the docker image: -###### docker pull myonara/webmud3:latest -To build an own image from the webmud3 directory: -###### docker build -f dockerfiles/ng-local.dockerfile -t myonara/webmud3:latest . +Please note: most of these features have been tested against [UNItopia](https://www.unitopia.de). We can not guarantee all features are working with your MUD server. -For standalone execution: -###### docker run -d -p 5000:5000 --name webmud3test myonara/webmud3:latest +- Telnet support -For swarm init: -###### docker stack deploy -c dockerfiles/w3_docker_compose_local.yml webmud3alocal + Provides a flexible and customizable socket interface that can establish a Telnet connection to any MUD server. Telnet Options are negotiated as necessary. -Prior to Version V0.0.40 there was a possiblity to manually edit the files and -load and test it outside docker. Take a look into ./Dockerfile -and perform the replace-steps to index.html and server.js manually, -if you really insist on executing without docker. + There is [work in progress](https://github.com/unitopia-de/webmud3/milestone/9). -Then the docker container is running on port 5000 (localhost:5000/webmud3) +- ANSI support + + The received text is displayed with ANSI color codes, providing a colorful and user-friendly representation in the frontend. + + There is [work in progress](https://github.com/unitopia-de/webmud3/milestone/11). + +- Reconnection + + The backend stays connected to the MUD even if the frontend is disconnected. This allows for seemless reconnections from the frontend. Every message received by the backend is cached meanwhile so nothing is lost. + +- Mobile Support + + The frontend is (and should always be) mobile optimized. + +## Roadmap + +We are currently working on the following features: + +- MXP Support + + [Milestone](https://github.com/unitopia-de/webmud3/milestone/8) + +- GMCP Support + + _Not planned yet_ + +## Deployments + +Currently, there is a [test deployment](https://unitopia-client.azurewebsites.net/) available. This deployment can be set for any given branch. To check which branch is currently deployed there, visit [Azure Deployments](https://github.com/unitopia-de/webmud3/actions/workflows/deploy_to_azure.yml). + +[![Build and deploy to azure](https://github.com/unitopia-de/webmud3/actions/workflows/deploy_to_azure.yml/badge.svg)](https://github.com/unitopia-de/webmud3/actions/workflows/deploy_to_azure.yml) + +## Releases + +There are no official releases just now. Stay tuned. + +## Setup for yourself + +Follow these steps to set up and run webmud3 locally: + +### Clone the Repository + +Clone the repository to your local machine using the following command: + +`git clone https://github.com/unitopia-de/webmud3.git` + +### Install Dependencies + +Navigate to the root directory of the project and install the necessary packages. This command will automatically install all required packages for both the frontend and backend: + +`npm install` + +### Set Environment Variables + +You need to set the following environment variables to configure the backend connection. You can do this either directly in your shell before starting the backend (or the client in completion), or by creating a .env file in the root directory. + +Example .env file: + +```bash +TELNET_HOST=127.0.0.1 # Required | the IP of your MUD +TELNET_PORT=23 # Required | the PORT of your MUD +SOCKET_ROOT=/socket.io # Required | the named socket for +HOST=0.0.0.0 # Optional, defaults to '0.0.0.0' | the IP the backend will listen for +PORT=5000 # Optional, defaults to 5000 | the PORT the backend will listen for +TELNET_TLS=false # Optional, defaults to 'false' | set this to true if you want a secure connection +SOCKET_TIMEOUT=900000 # Optional, defaults to 900000 (15 min) | timeout for any lost frontend<->backend connection +CHARSET=utf8 # Optional, defaults to 'utf8' +``` + +> [!TIP] +> You can also put this file in any compiled directory, like `/backend/dist` after you run `npm run build`. + +Ensure that the frontend is configured to connect to the correct backend. This can be set by editing the backendUrl in the frontend/src/environments/environment.ts file: + +```ts +export const environment = { + // .. other properties might appear here + backendUrl: "http://localhost:5000", // Set this to your backend's IP or URL +}; +``` + +> [!WARNING] +> This must be done at compile time. There is (currently) no way to change this setting after compilation! + +### Build & Run + +To build and run both the frontend and backend simultaneously, use the following command in the root directory: + +`npm run start` + +This command builds the frontend and integrates it into the backend, which serves the frontend during runtime. + +To visit it, open your browser at `http://localhost:5000` or to be more precise: `http::` where HOST and PORT are the repective [Options](#set-environment-variables) during runtime. + +Alternatively, you can build and run them separately: + +Build or start the frontend: + +```bash +cd frontend +npm run build or npm run start +``` + +Build or start the backend: + +```bash +cd backend +npm run build or npm run start +``` + +## Docker + +Docker images for easy deployment will follow. Stay tuned. + +## Contributions + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. + +You can either create an issue for whatever problem you have (dont by shy - there are no regulations on how to create such an issue - so feel free to describe your problems). + +Or you can fix problems by yourself. Follow these instructions: + +### Ensure your client is up and running + +Follow the instructions at [Setup](#setup) and make sure you can connect to a MUD. You will have to clone this repository into you own account. We recommend you to check out the "develop" branch for easy integration since this is our default branch. + +### Make your changes + +We recommend you to to create a new branch out of your newly copied "develop" branch of your own repository. +Make your changes there. + +### Test your changes + +To speed things up, you should run `npm run test` at the root to run every unit test in the repo. This might help you to identify bugs caused by your changes (and only yours hopefully). If you want to integrate your changes to the official repository, your PR will be checked anyways so its better to do it beforehand. + +### Create a PR + +Create a PR targeting unitopia.de/develop if you want to integrate this changes to the official repository. A previously created issue on the unitopia repository might help you to integrate faster and avoid discussions with the staff. Your PR will be checked against automated tests and needs to be approved by one or more official members of unitopia. + +## License + +This project is licensed under the GPL-3.0 license - see the [LICENSE](LICENSE) file for details. + +## Contact + +Any troubles? Feel free to reach out: + +- @mystiker Can help you with any project related questions and meta questions (git or deployments for example). +- @myonara Can help you with anything MUD related (protocols, mudlib, ..). diff --git a/backend/src/core/environment/types/environment-keys.ts b/backend/src/core/environment/types/environment-keys.ts index 5c008371..f7680bf1 100644 --- a/backend/src/core/environment/types/environment-keys.ts +++ b/backend/src/core/environment/types/environment-keys.ts @@ -1,9 +1,9 @@ export type EnvironmentKeys = - | 'HOST' - | 'PORT' - | 'TELNET_HOST' - | 'TELNET_PORT' - | 'TELNET_TLS' + | 'HOST' // Optional. Defaults to '0.0.0.0' + | 'PORT' // Optional. Defaults to 5000 + | 'TELNET_HOST' // Required. Example '127.0.0.1' + | 'TELNET_PORT' // Required. Example '23' + | 'TELNET_TLS' // Optional. Defaults to 'false' | 'SOCKET_TIMEOUT' // in milliseconds | default: 900000 (15 min) | determines how long messages are buffed for the disconnected frontend and when the telnet connection is closed - | 'SOCKET_ROOT' - | 'CHARSET'; + | 'SOCKET_ROOT' // Required. Example '/socket.io' + | 'CHARSET'; // Optional. Defaults to 'utf8';