forge/Vervis
1
0
Fork 0
Code Pull requests Activity

README: Revise text

Browse source
This commit is contained in:
Pere Lev 2024-10-20 01:55:16 +03:00
parent d35b26c1c2
commit 4b113b8a20
No known key found for this signature in database
GPG key ID: 5252C5C863E5E57D
2 changed files with 117 additions and 139 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
INSTALL.md
View file

@ -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!

218
README.md
View file

@ -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 <https://vervis.peers.community>, 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:
<https://vervis.peers.community/repos/rjQ3E>
There is a backup repo, not always up to date though, at:
<https://codeberg.org/forgefed/vervis>
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
[<img src="https://nlnet.nl/logo/banner.png" alt="NLnet foundation logo" width="20%" />](https://nlnet.nl)
[<img src="https://nlnet.nl/image/logos/NGI0Entrust_tag.svg" alt="NGI Zero Entrust Logo" width="20%" />](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