Vervis/README.md

Vervis is a free, open-source federated forge backend server:

• 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

Navigation

• Project on Codeberg
• Support the development via Liberapay or OpenCollective
• Official Docker image
• Demo instances:
  • Fig
  • Grape
  • Walnut

Features

The current focus is the classic core features for collaboration:

• 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

SSH Client Config

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.

Add the following to your ~/.ssh/config file (or create it if it doesn't exist), replacing the Host with your instance's domain:

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.

HTTPS clone:

$ git clone https://vervis.peers.community/repos/rjQ3E vervis

SSH clone and push:

If your system username and Vervis username are identical:

$ git clone vervis.peers.community:rjQ3E vervis

If usernames are different:

$ git clone luke@vervis.peers.community:rjQ3E vervis

Deployment

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

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.

Development

To prepare a development environment, follow the instructions in INSTALL.md.

Federation & API

See FEDERATION.md & API.md.

Contributing

Vervis is free, open-source software licensed under AGPLv3.

You can open issues for bugs you've found or features you think are missing. You can also submit pull requests to this repository.

Matrix room: #general-forgefed:matrix.batsense.net

Finding your way in the codebase

Folders:

• app: main functions of the web app, for regular build and for development modes
• config: Settings the app reads when it launches, some defined by a human and some auto-generated
• .git: Internal version control data of this repo
• embed: Files embedded into the app source code at build time (using TH)
• hook-darcs & hook-git: main functions for VCS hook programs to be inserted into every repo hosted by the app
• migrations: Helper files for DB migrations: New entities added & model files for migrations involving data manipulation
• src: Web app Haskell source code, built as a library whose modules are used by the various executables
• static: Static files (such as CSS and fonts) served by the web app (no such files at the moment)
• templates: UI page and widget templates (.hamlet for HTML, .cassius for CSS)
• test: No tests have been written yet
• th: Domain-specific language snippets, from which code is generated using TH

Files:

• .gitignore
• th/routes
• th/models
• update-deps.sh
• bindist.sh

Haskell modules in src:

• Non-Vervis modules:
  • Modules ending with Local:
  • The rest:
• Vervis.Data
• Vervis.Persist
• Vervis.Fetch
• Vervis.Serve
• Vervis.Query
• Vervis.Web
• Primary web app support modules:
  • Vervis.Foundation
  • Vervis.Application
  • Vervis.Settings
  • Vervis.Model
  • Vervis.Migration
• Primary web app logic modules:
  • Vervis.Actor
  • Vervis.Handler
  • Vervis.Client
• Vervis.Ssh

Testing the production image

When Vervis is built in development mode (the flag is set in stack.yml and can be overriden when running stack build), it works with plain HTTP, but in production mode (e.g. when using the official prebuilt image), it requires HTTPS, a domain, and the standard HTTP(S) ports.

Instructions for testing a production image, assuming we'll use dev.example as the server's domain name:

1. The usual ./prepare-state.sh and cp config/settings-sample-prod.yml config/settings.yml
2. On the host system, edit /etc/hosts, adding the line 127.0.0.1 dev.example
3. In config/settings.yml, set the domain to dev.example
4. Run ./create-self-cert.sh to generate a self-signed certificate for dev.example
5. In docker-compose.yml, uncomment the nginx service
6. In nginx.conf,
   • Update the domain to dev.example
   • Uncomment the self-signed cert paths
7. docker-compose up

License

AGPLv3+. See COPYING.

Funding

This project is funded through the NGI Zero Entrust Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.