From 4b113b8a20643d193edd83d501cc9f85cd94c7ac Mon Sep 17 00:00:00 2001 From: Pere Lev Date: Sun, 20 Oct 2024 01:55:16 +0300 Subject: [PATCH] README: Revise text --- INSTALL.md | 38 +--------- README.md | 218 ++++++++++++++++++++++++++++------------------------- 2 files changed, 117 insertions(+), 139 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 29fee60..423c3fe 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,37 +1,5 @@ -# 2024 update - docker setup - -I'll update this file properly soon, but for now, instructions for deployment -using docker: - -1. In `create-db.sql`, update the `vervis` DB user's password -2. Create and edit `config/settings.yml` based on - `config/settings-sample-prod.yml`, remember to set the same DB password here -3. In `docker-compose.yml`, update the database superuser password (it's the - password for the `postgres` superuser, not `vervis`) -4. Create initial state: `./prepare-state.sh` -5. Ready for launch! `docker-compose up -d` - ---- - -Vervis is still in early development and the build process gets updates once in -a while, but this file tries to keep up and list the latest instructions for -running a Vervis instance. - -At the time of writing, you can get a running Vervis instance if you follow the -steps below. - -UPDATE: There is a binary build you can use instead of building from source. It -can be found [here](https://box.angeley.es/nextcloud/s/oWHmQDtWTAfPR4Z). If you -use it, verify the download using `sha256sum` and `gpg`, make sure the settings -in your `config/settings.yml` (see below) match the downloaded file paths, and run the -web app using `./bin/vervis` and not `stack run`. This may be confusing; -hopefully I'll make a nicer binary release soon :) - -2022 UPDATE: The binary release is unavailable right now. But a docker image is -being prepared. More news soon. - -2024 UPDATE: For production hosting and deployment with Docker, use the -`Dockerfile` and `docker-compose.yml` files in this repo's root directory. +These are the instructions for manual installation of Vervis. If you're looking +for instructions for Docker based deployment, see [README.md](README.md). # (1) System libraries @@ -191,7 +159,7 @@ missing in the filesystem. You can ask Vervis to generate missing files, and load the rest as usual: $ touch _keyfile_write_missing - $ stack run + $ stack run -- config/settings.yml Browse to `http://localhost:3000` and have fun! diff --git a/README.md b/README.md index c6a9bae..68a37d1 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,57 @@ -# Vervis +Vervis is a **free, open-source federated forge backend server**: -**Vervis** is a project hosting and management application, with a focus on -software projects and decentralization. There is still a lot to do, but if you'd -like to try it, a few things more or less work. See below for details. +- A platform for hosting and collaboration on software projects +- A reference implementation of the [ForgeFed][] forge federation protocol, + which is an extension of ActivityPub, the protocol that drives the Fediverse +- A decentralized network in which people on one server can seamlessly + collaborate with people from another server, including non-Vervis software + that implements ForgeFed +- Vervis is still in **pre-alpha phase** and not ready for production use! +- Provides a temporary static UI, to be replaced by the [Anvil][] frontend + client -Vervis is free software, and is committed to software freedom. Most of its code -is in the public domain using the CC0 Public Domain Dedication. The application -as a whole however is released under AGPL version 3. For the legal details, see -the file `COPYING`. Please use and reuse Vervis for a Good purpose, and share -your work too in the same spirit. +## Navigation -## Try It +- [Project on Codeberg][Repo] +- Support the development via [Liberapay][] or [OpenCollective][] +- [Official Docker image][Image] +- Demo instances: + - [Fig][] + - [Grape][] + - [Walnut][] -You can either use the existing instance mentioned below, or install your own -instance (see `INSTALL.md`). +## Features -My focus has been on writing the backend side of features and exploring various -experimental features. As a result, the user interface and visual design and -page styles (i.e. the whole UX and UI) are in a bad shape right now, so I want -to write a few little guidelines to help you find your way until this situation -improves. +The current focus is the classic core features for collaboration: -There is a Vervis instance running at , and I -store my code on it. Feel free to use it and try it, however do please treat it -as a demo, as it's not a reliable stable instance for general use yet. If for -any reason you do with to keep some code and tickets etc. on it for actual use, -please contact me to let me know. +- Repositories + - Git + - Darcs +- Issue tracking +- Pull requests +- And of course federation! Including, eventually, with other forge projects + working on implementing federation, such as [Forgejo][] and [GitLab][] -Here are the steps to make the most out of it at this point (at least at the -time of writing, I'll try to keep this little tutorial up to date)! +## SSH Client Config -1. Create an SSH key if you don't have one. Most likely you do, for pushing to - your existing repos hosted on your favorite project hosting platform. -2. Browse to the instance I linked above, and click *Sign up*. Choose a - username and a password. Email address is currently optional on this - instance, but it's going to be required soon and used for things like - password reset, so please do provide a real email address. -3. Log in. Once you log in, the front page will change, and among other things, - it will link to your SSH keys. Go there to add your SSH key. In the - algorithm box you paste the first part e.g. `ssh-rsa`, and in the second box - you paste the long scary part that follows it. -4. The front page also links you to repos and projects, you can create a - project and open tickets. You can also create a Git or Darcs repo, and - optionally associate it with a project. A project can have any number of - repos asociated with it, sharing the same ticket tracker. Creating a project - or repo may ask you to create a project or repo role; the front page has - links for creating these -5. You can browse all the projects and repos hosted on the instance. -6. Add the following to your `~/.ssh/config` file, or create it if doesn't - exist. To be honest I'm not sure it's still required, and haven't tested - yet. If you find that this step is unnecessary and everything works without - it, let me know :) +Vervis comes with its own SSH server, which usually requires some configuration +to be set in your SSH client, if you'd like to be able to push and pull repos +via SSH. - Host vervis.peers.community - KexAlgorithms +diffie-hellman-group1-sha1 - ControlMaster no - ForwardAgent no - ForwardX11 no - Ciphers +aes256-cbc - MACs +hmac-sha1 - PubkeyAcceptedKeyTypes +ssh-rsa - HostKeyAlgorithms +ssh-rsa +Add the following to your `~/.ssh/config` file (or create it if it doesn't +exist), replacing the Host with your instance's domain: -Once you create a repository, it is possible that initially, trying to look at -it will give you 404. It should be okay though once you push some commit into -it. - -The examples below use Git, but it's exactly the same for Darcs. They are -equally supported. +``` +Host fig.fr33domlover.site + KexAlgorithms +diffie-hellman-group1-sha1 + ControlMaster no + ForwardAgent no + ForwardX11 no + Ciphers +aes256-cbc + MACs +hmac-sha1 + PubkeyAcceptedKeyTypes +ssh-rsa + HostKeyAlgorithms +ssh-rsa +``` Cloning repositories works over (unauthenticated) HTTPS and (authenticated) SSH. @@ -86,48 +70,70 @@ If usernames are different: $ git clone luke@vervis.peers.community:rjQ3E vervis -A few more little notes: +## Deployment -- No password reset, it's already implemented but not deployed yet at the time - of writing these words -- A few more features are available, such as ticket workflows and ticket claim - requests, but they are less important so I'm not going into them at this - point -- Deletion of users, projects and repos may not work -- Login session should last for 2 hours after last access -- The instance I'm running serves only HTTPS, no plain HTTP -- There's no HTTPS push -- Merge requests not implemented yet -- I started working on federation using ActivityPub, I'll update here when it's - ready for trying against ActivityPub clients and servers -- Feedback is very very very very very welcome and needed!!! :) +### Tech stack + +- **Haskell** programming language +- **Yesod** web framework +- **PostgreSQL** database for most data +- Some data in **SQLite** databases +- The work-in-progress [Anvil][] frontend uses: + - **Svelte** + - **Skeleton** + - **Tauri** + +### Requirements + +- **PostgreSQL** 9.5+ + +### Docker + +The repository includes deployment configurations for **Docker and +docker-compose**. + +1. Install [Docker][] +2. In `create-db.sql`, update the `vervis` DB user's password +3. Create and edit `config/settings.yml` based on + `config/settings-sample-prod.yml`, remember to set the same DB password here +4. In `docker-compose.yml`, update the database superuser password (it's the + password for the `postgres` superuser, not `vervis`) +5. Create initial state: `./prepare-state.sh` +6. Ready for launch! `docker-compose up -d` + +```shell +sudo apt install docker-compose docker.io +vim create-db.sql +cp config/settings-sample-prod.yml config/settings.yml +vim config/settings.yml +vim docker-compose.yml +./prepare-state.sh +docker-compose up -d +``` + +### Manual Installation + +For manual/custom installation steps, see [INSTALL.md](INSTALL.md). + +## Development + +To prepare a development environment, follow the instructions in +[INSTALL.md](INSTALL.md). ## Federation & API See `FEDERATION.md` & `API.md`. -## Installation +## Contributing -See `INSTALL.md`. +Mastodon is **free, open-source software** licensed under **AGPLv3**. -## Using +You can open issues for bugs you've found or features you think are missing. +You can also submit pull requests to this repository. -See the .cabal file for more info and link to project website and version -control. +**Matrix room**: [#general-forgefed:matrix.batsense.net][Matrix] -The official download location is the Darcs repository: - - - -There is a backup repo, not always up to date though, at: - - - -See the file `INSTALL.md` for a detailed usage and deployment guide. The file -`ChangeLog` explains how to see the history log of the changes done in the -code. `NEWS.md` provides a friendly overview of the changes for each release. - -## Finding your way in the codebase +### Finding your way in the codebase Folders: @@ -190,19 +196,9 @@ Haskell modules in `src`: - `Vervis.Client` - `Vervis.Ssh` -## Reporting Bugs and Suggesting Features +## License -If you found a bug, or you have an idea, a feature request or a wishlist item, -open a ticket for it! Even if you're going to implement something or try to -solve it. - -If you're going to implement some feature or fix some bug you found, **start by -opening a ticket** -[here](https://codeberg.org/ForgeFed/Vervis/issues) so that other -people will know which features are being developed and who does what. - -UPDATE: The ticket tracker is temporarily unavailable. You can instead contact -[Pere](https://perelev.site) to report issues and to coordinate work. +AGPLv3+. See `COPYING`. ## Funding @@ -214,3 +210,17 @@ This project is funded through the [NLnet foundation logo](https://nlnet.nl) [NGI Zero Entrust Logo](https://nlnet.nl/entrust) + +[Anvil]: https://codeberg.org/Anvil/Anvil +[Docker]: https://docs.docker.com +[ForgeFed]: https://forgefed.org +[Forgejo]: https://forgejo.org +[GitLab]: https://gitlab.com +[Image]: https://codeberg.org/ForgeFed/Vervis/packages +[Liberapay]: https://liberapay.com/ForgeFed +[Matrix]: https://matrix.to/#/#general-forgefed:matrix.batsense.net +[OpenCollective]: https://opencollective.com/forgefed +[Repo]: https://codeberg.org/ForgeFed/Vervis) +[fig]: https://fig.fr33domlover.site +[grape]: https://grape.fr33domlover.site +[walnut]: https://walnut.fr33domlover.site