diff --git a/docs/dev/adr/index.md b/docs/dev/adr/index.md new file mode 100644 index 0000000..b5050aa --- /dev/null +++ b/docs/dev/adr/index.md @@ -0,0 +1,10 @@ +--- +title: ADRs +parent: Development Guide +last_modified_date: 5.6.2025 +--- + +# Architecture Decision Records + +Here we are documenting all the decision records to make it easier in future to review them and revise them if necessary. +Let's keep them simple and to the point. \ No newline at end of file diff --git a/docs/dev/adr/network-connectivity-of-services.md b/docs/dev/adr/network-connectivity-of-services.md new file mode 100644 index 0000000..1b1de49 --- /dev/null +++ b/docs/dev/adr/network-connectivity-of-services.md @@ -0,0 +1,31 @@ +--- +title: Network Connectivity of Services +parent: ADRs +last_modified_date: 5.6.2025 +--- + +# Network Connectivity of Services +## Decision +We decided to use Docker Compose file to define a service name for each deployed service then it can be reused as the URL for other services in the same docker network although they are in separate repos and deployed separately. + +### Option 1: Docker Compose + +#### Pros +- We can simply use `http:://:port` as the url if they are in same docker network +#### Cons +- network name in the compose file need to be maintained if it is different from `coolify` + +### Option 2: Using consistent custom container name + +#### Pros +- We can simply use `http:://:port` as the url if they are in same docker network +#### Cons +- We are losing the rolling update feature (continuous deployment without downtime) + +### Option 3: No config -> use container name + +#### Pros +- Simple +#### Cons +- Container name will change after each deployment + - e.g. we need to update `telegram-interface` environment variable after each `linguly-core` update \ No newline at end of file diff --git a/docs/dev/index.md b/docs/dev/index.md new file mode 100644 index 0000000..fd8c4c2 --- /dev/null +++ b/docs/dev/index.md @@ -0,0 +1,10 @@ +--- +title: Development Guide +last_modified_date: 31.5.2025 +--- + +# Development Guide + +In this section we are trying to document all the necessary information for contributors who want to quickly develop Linguly further. + +The guides are either step by step guide to setup the or troubleshoot or pointing to the necessary resources such as external resources or the readme files in the respective repos. \ No newline at end of file diff --git a/docs/dev/troubleshoot/docs.md b/docs/dev/troubleshoot/docs.md new file mode 100644 index 0000000..124770f --- /dev/null +++ b/docs/dev/troubleshoot/docs.md @@ -0,0 +1,14 @@ +--- +title: Docs +parent: Troubleshoot +last_modified_date: 1.6.2025 +--- + +# Troubleshoot Docs + +## Just the Docs + +### Image is not rendered in the final doc +Images may not be shown although you see them in a preview. It is likely because the paths are slightly different in the generated files and you might need to go one level back to the parent folder. +e.g. [check here](https://github.com/Linguly/docs/blob/main/docs/setup/how-to-setup.md?plain=1#L40) + diff --git a/docs/dev/troubleshoot/index.md b/docs/dev/troubleshoot/index.md new file mode 100644 index 0000000..712382b --- /dev/null +++ b/docs/dev/troubleshoot/index.md @@ -0,0 +1,9 @@ +--- +title: Troubleshoot +parent: Development Guide +last_modified_date: 1.6.2025 +--- + +# Troubleshoot + +Here we want to document all the troubleshooting experiences we face during the Linguly development. give us a star if it helped saving seconds for you : ) \ No newline at end of file diff --git a/docs/dev/troubleshoot/linguly-core.md b/docs/dev/troubleshoot/linguly-core.md new file mode 100644 index 0000000..cc1380c --- /dev/null +++ b/docs/dev/troubleshoot/linguly-core.md @@ -0,0 +1,12 @@ +--- +title: Linguly Core +parent: Troubleshoot +last_modified_date: 1.6.2025 +--- + +# Troubleshoot Linguly Core + +## MongoDB + +A TLS connection or so maybe because of the default IP filtering in Mongo Atlas. So don't forget to add your IP there or disable the feature if you are not storing sensitive data there. + diff --git a/docs/dev/troubleshoot/telegram-interface.md b/docs/dev/troubleshoot/telegram-interface.md new file mode 100644 index 0000000..0604f9f --- /dev/null +++ b/docs/dev/troubleshoot/telegram-interface.md @@ -0,0 +1,18 @@ +--- +title: Telegram Interface +parent: Troubleshoot +last_modified_date: 2.6.2025 +--- + +# Troubleshoot Telegram Interface + +## General + +If the messages and chat flow are acting weirdly, make sure you have followed the following: + +- Don't forget to put `await` before any context change and does contexts are not changing in wrong order. +- If you want to leave a scene, that should be the last command. +- Except leaving the scene, if you are using `reply`, that should be the last command. +- Make sure all `reply`s and async functions are awaited, otherwise the session store update will happen before all the changes and you might loose the updates in Redis. + +> Note: to debug Telegraf, you can use this environment variable: `DEBUG=telegraf:*` \ No newline at end of file diff --git a/docs/dev/used-techs/docker.md b/docs/dev/used-techs/docker.md new file mode 100644 index 0000000..01aa71e --- /dev/null +++ b/docs/dev/used-techs/docker.md @@ -0,0 +1,6 @@ +## Useful Commands + +- List all the running dockers +```bash +docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" +``` \ No newline at end of file diff --git a/docs/setup/how-to-setup.md b/docs/setup/how-to-setup.md index a93dea4..e426aae 100644 --- a/docs/setup/how-to-setup.md +++ b/docs/setup/how-to-setup.md @@ -37,8 +37,9 @@ Follow the quick installation from Coolify to install it in your server: - add Linguly's [Telegram Interface](https://github.com/Linguly/telegram-interface) and [Linguly Core](https://github.com/Linguly/linguly-core) using [the Github app integration](https://youtu.be/taJlPG82Ucw?feature=shared&t=1898) or just clone the latest - configure the `BOT_TOKEN` and `LINGULY_CORE_BASE_URL` for the telegram interface using the environment variable > **NOTE**: `LINGULY_CORE_BASE_URL` can be your Linguly Core container name plus the exposed port e.g. `http://-:3001` - ![](./images/container-name.png) - ![](./images/environment-variables.png) + + ![](../images/container-name.png) + ![](../images/environment-variables.png) ## 3- Setup an LLM Model diff --git a/docs/setup/linguly-core-in-coolify.md b/docs/setup/linguly-core-in-coolify.md new file mode 100644 index 0000000..53781d2 --- /dev/null +++ b/docs/setup/linguly-core-in-coolify.md @@ -0,0 +1,16 @@ +--- +title: Setup Linguly Core in Coolify +parent: Setup +nav_order: 2 +--- + +# Setup Linguly Core in Coolify + +## Docker Network +- Setup it in same network as other services +- Setup in `coolify` default network otherwise need to modify network in the docker-compose.yaml +- More info in [this ADR](../dev/adr/network-connectivity-of-services.md) + +## Environment Variables +Add the environment variables based on the [readme](https://github.com/Linguly/linguly-core?tab=readme-ov-file#environment-variables-for-local-setup). +