Skip to content

Commit

Permalink
Update documentation and README
Browse files Browse the repository at this point in the history
  • Loading branch information
@bkis
bkis committed Jun 26, 2023
1 parent 782ab5e commit 77ba16e
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 24 deletions.
22 changes: 12 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
<img width="72" height="72" align="right" style="position: absolute; top: 0; right: 0; padding: 12px;" src="assets/logo.png" alt="Tekst logo"/>
<!-- <img width="72" height="72" align="right" style="position: absolute; top: 0; right: 0; padding: 12px;" src="assets/logo.png" alt="Tekst logo"/> -->

# Tekst <!-- omit in toc -->

*...as in* **T**ext **E**xploration *and* **K**nowledge **S**tructuring **T**ool
...as in `T`ext `E`xploration and `K`nowledge `S`tructuring `T`ool

> ⚠ Tekst is still somewhere between a conceptual phase and its early stages of development. As of now there's no stable (let alone production-ready) version available.
> As soon as we're ready for it, the VedaWeb platform will become the first public instance of Tekst. Until then, you are welcome to follow the development of Tekst in this very repository.
> 🏗 Tekst is still in a pre-alpha stage. As of now there's no complete (let alone production-ready) version available.
> As soon as we're ready for it, the new [VedaWeb platform](https://vedaweb.uni-koeln.de/rigveda) will become the first public instance of Tekst. Until then, you are welcome to follow the development of Tekst in this very repository.
Tekst is a collaborative, web-based research platform for displaying, linking, exploring, and enriching resources on natural language texts. It is developed within the scope of the [VedaWeb 2.0](https://vedaweb.uni-koeln.de/) research project on Old Indic texts, where it constitutes the technical basis of the research platform "VedaWeb", which will be launched in its new form as part of the project's efforts.
Tekst is a collaborative, web-based research platform for aligning, displaying, linking, exploring, and enriching resources on natural language texts (and more). It is developed within the scope of the [VedaWeb 2.0](https://vedaweb.uni-koeln.de/) research project on Old Indic texts, where it constitutes the technical basis of the research platform "VedaWeb", which will be launched in its new form as part of the project's efforts.

This is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) containing the Tekst server project ([Tekst-API](Tekst-API)), the Tekst client project ([Tekst-Web](Tekst-Web)) as well as general information, documentation and the resources needed to deploy an instance of the Tekst platform for yourself or your research project.

## General information and documentation

## Contents <!-- omit in toc -->
You are looking for information on concepts, use cases, features, setup, deployment or administration of the Tekst platform?

- [What is Tekst, really?](#what-is-tekst-really)
**[📑 Click here to go to the Tekst platform's documentation and manual!](https://vedawebproject.github.io/Tekst)**


## What is Tekst, really?
## Development

🚧 **TODO:** Answer the question.
This is a monorepo containing the codebases of the Tekst server project ([Tekst-API](Tekst-API)) and the Tekst client project ([Tekst-Web](Tekst-Web)) as well as for the [documentation](https://vedawebproject.github.io/Tekst) and the resources needed to deploy an instance of the Tekst platform for yourself or your research project.

The different project directories contain their own respective `README.md` files covering the development tooling and overall project setup.
22 changes: 16 additions & 6 deletions docs/content/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,34 @@
# Introduction

Tekst is a collaborative, web-based research platform for displaying, linking, exploring, and enriching resources on natural language texts. It has been developed within the scope of the [VedaWeb 2.0](https://vedaweb.uni-koeln.de/) research project on Old Indic texts, where it constitutes the technical basis of the research platform *VedaWeb*.
Tekst is a collaborative, web-based research platform for aligning, displaying, linking, exploring, and enriching resources on natural language texts (and more). It is developed within the scope of the [VedaWeb 2.0](https://vedaweb.uni-koeln.de/) research project on Old Indic texts, where it constitutes the technical basis of the *VedaWeb* research platform.


## Use Cases

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
(WIP)


## Concepts

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
(WIP)


## Features

### Closed Mode
...
This list is not exhaustive, but includes some features that might be decisive for certain use cases:

- Manage multiple independent, potentially differently structured texts and arbitrary related resources in a single platform instance
- One common user base for the whole platform
- UI colors will adapt to the currently selected working text for visual unambiguity
- Built-in [i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization) (with an extensible set of languages)
- Integrated user management with authentication and role-based as well as owner-based authorization
- *Closed Mode* to run the platform purely administrator-driven, turning off registration for arbitrary users
- Extensively typed and documented server API (via [OpenAPI](https://spec.openapis.org/oas/v3.0.2) specification) and built-in interactive API documentation (via [Swagger UI](https://github.com/swagger-api/swagger-ui) and/or [ReDoc](https://github.com/Redocly/redoc)), all thanks to [FastAPI](https://github.com/tiangolo/fastapi)


## Caveats

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Depending on your requirements, you might want to consider the following list of potential shortcomings:

- SEO: The (web-)client is a SPA (Single Page Application) that is rendered in the browser (as opposed to SSR), so visibility to search engines is somewhat limited.
- UI responsiveness: The user interface (especially the public-facing part) is responsive to the use on hand-held mobile devices. That being said, it was primarily developed for desktop-based usage. This might show in places.
26 changes: 18 additions & 8 deletions docs/content/setup.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Setup

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

## General Requirements

## Configuration
The follwing requirements apply to either deployment strategy. Each deployment strategy then comes with its own respective additional requirements.

The following values can be configured in an `.env` file to match your deployment environment and needed features. Use the below list for guidance. The configuration defaults to values for a full-featured, Docker-based production environment served at `/` (root path). There *are* things you *have to* configure for them to work, though. By default, the application will later be available locally on port `8087` at `127.0.0.1`.
- A server to deploy Tekst to (the deployment instructions below assume a Linux-based server with Docker and Docker Compose installed, as this is the recommended setup strategy)
- Access to a working, reliable **SMTP server** to send out emails containing verification links, password reset links, etc. It is important that this SMTP server is well-configured so the emails it sends actually reach their recepients. Whether you use a third-party SMTP server (like the one of your email provider) or your own self-hosted one is up to you. If you plan to run Tekst in [closed mode](index.md#closed-mode) (only one or more administrators, no public users who can create content), this requirement is **not strictly necessary**.


## Deployment
## Configuration

### General Requirements
The following values can be configured in an `.env` file to match your deployment environment and needed features. Use the below list for guidance. The configuration defaults to values for a full-featured, Docker-based production environment served at `/` (root path). There *are* things you *have to* configure for them to work, though. By default, the application will later be available locally on port `8087` at `127.0.0.1`.

The follwing requirements apply to either deployment strategy. Each deployment strategy then comes with its own respective additional requirements.

- Access to a working, reliable **SMTP server** to send out emails containing verification links, password reset links, etc. It is important that this SMTP server is well-configured so the emails it sends actually reach their recepients. Whether you use a third-party SMTP server (like the one of your email provider) or your own self-hosted one is up to you. If you plan to run Tekst in [closed mode](index.md#closed-mode) (only one or more administrators, no public users who can create content), this requirement is **not strictly necessary**.
## Deployment

### Docker (recommended)
### Using Docker (recommended)

As with every Docker-based deployment, the benefits of this approach are a reproducable deployment environment and an overall isolated setup.

Expand Down Expand Up @@ -60,3 +60,13 @@ docker compose up
Add the `-d` flag to run it in detached mode (in the background).

Read [this](https://docs.docker.com/engine/reference/commandline/compose/) to learn how to stop, start, reset (...) the application stack using Docker Compose.


### On host system

#### Requirements
> 🏗 TODO

#### Instructions
> 🏗 TODO

0 comments on commit 77ba16e

Please sign in to comment.