sr.ht-docs: Start documenting dev environment setup v1 PROPOSED

Conrad Hoffmann: 1
 Start documenting dev environment setup

 2 files changed, 116 insertions(+), 0 deletions(-)
Export patchset (mbox)
How do I use this?

Copy & paste the following snippet into your terminal to import this patchset into git:

curl -s https://lists.sr.ht/~sircmpwn/sr.ht-dev/patches/29781/mbox | git am -3
Learn more about email & git

[PATCH sr.ht-docs] Start documenting dev environment setup Export this patch

Start by adding a few more notes to the `hacking` doc and add a
sub-document with detailed instructions for setting up meta.sr.ht.

Detailed descriptions for other services will follow the same pattern.
 hacking.md            | 56 ++++++++++++++++++++++++++++++++++++++++
 hacking/meta.sr.ht.md | 60 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 hacking/meta.sr.ht.md

diff --git a/hacking.md b/hacking.md
index 7c00e75..0e440f3 100644
--- a/hacking.md
+++ b/hacking.md
@@ -11,12 +11,68 @@ contributing to SourceHut.
Here are some tips to expedite the installation procedure:

* A PostgreSQL database and Redis server are always required.
* Some services require a S3-compatible storage backend - install minio.
* Generally, you can skip the webhooks daemons unless you need them.
* Always prefer package installations for obtaining dependencies.
* You can *usually* get away without configuring the outgoing mail settings,
  but you may still have to generate a PGP key to get things started up.
* You can skip setting up a reverse proxy and use our development servers via
  `python3 run.py` instead.
* Some services depend on other services (see instructions for each service),
  but in any case you should start with setting up meta.sr.ht

## Required daemons

### PostgreSQL

The instructions will contain commands like `createdb git.sr.ht`. This assumes
that you have PostgreSQL up and running and created a user by the same name as
your login user name. Otherwise, the commands may have to be adjusted. Consult
your distribution's or PostgreSQL's documentation for details.

### Redis

Simply installing Redis and having it running on the default port should be

### Minio

*NOTE:* only needed for certain services, see list below

Install the minio server and set `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD` in
the config file. While you shouldn't do this in production you can use these
values as `s3-access-key` and `s3-secret-key` in the `[objects]` section of
your `config.ini`. To make sure to not accidentally expose your setup on the
network, also set `MINIO_OPTS="--address"`

Install the minio client. Upstream refers to it as `mc`, but most distributions
package it as `mcli` to avoid ambiguity. Set up an alias for your local
connection, e.g.:

    mcli alias set local/ http://localhost:9123 <username> <password>

## Required tooling

For building from source, some tools are required that are not a dependency of
the packages. They are:

* `sassc` for CSS pre-processing
* `npm` for minifying CSS
* `go` for compiling the Go APIs

## List of services

* [meta.sr.ht](/hacking/meta.sr.ht.md)
* todo.sr.ht
* hub.sr.ht
* git.sr.ht
* hg.sr.ht
* pages.sr.ht
* paste.sr.ht
* lists.sr.ht
* man.sr.ht
* builds.sr.ht

# Sending Patches

diff --git a/hacking/meta.sr.ht.md b/hacking/meta.sr.ht.md
new file mode 100644
index 0000000..35411d8
--- /dev/null
+++ b/hacking/meta.sr.ht.md
@@ -0,0 +1,60 @@
title: Hacking on SourceHut - meta.sr.ht
toc: false

# Hacking on meta.sr.ht

Start by cloning the repository somewhere, along with core.sr.ht:

    cd ~/src
    git clone --recurse-submodules https://git.sr.ht/~sircmpwn/core.sr.ht
    git clone https://git.sr.ht/~sircmpwn/meta.sr.ht
    cd meta.sr.ht

Then configure `PYTHONPATH` to look up these directories, and set up

    export PYTHONPATH=$HOME/src/core.sr.ht:$HOME/src/meta.sr.ht
    export SRHT_PATH=$HOME/src/core.sr.ht/srht

Generate static assets and build the API:

    cd api && go build

The next step is getting the configuration right for meta.sr.ht. Start with the
example config file (`mv config.example.ini config.ini`) and populate the
various fields. For the service-independent `[sr.ht]` section, the keys can be
generated with `srht-keygen` found in core.sr.ht and the `redis-host` field
should be set to `redis://`. Additionally, set
`global-domain=` to ensure cookies are created with the correct

The `[mail]` section doesn’t need to be populated, except for the PGP key. See
the comment in the sample config for instructions. Make sure to use an absolute
path to the key, as we will link to this config file from other places.

Then comes the `[meta.sr.ht]` section. Set `origin=` (port
same as `debug-port`). Append `?sslmode=disable` to the database
connection-string to allow the services to connect without TLS.

To create and initialize the database:

    createdb meta.sr.ht

If you later update meta.sr.ht, run `./metasrht-migrate upgrade head` to run
database migrations.

Create a new admin user:

    ./metasrht-manageuser -t admin root

Once all that preparation work is done, meta.sr.ht should be ready to be started:

    ./api/api &
    python run.py

You should be able to browse your local meta.sr.ht instance at
http://localhost:5000 and e.g. create new users and log in as those.
If you are ok with this pattern I will gradually add the instructions 
for the other services.
Overall LGTM

On Thu Feb 24, 2022 at 5:06 PM CET, Conrad Hoffmann wrote: