Conrad Hoffmann: 1 Start documenting dev environment setup 2 files changed, 116 insertions(+), 0 deletions(-)
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 -3Learn more about email & git
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.
* Some services require (or may optionally make use of) an S3-compatible storage backend. [Minio] is recommended for this purpose.
* 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
* Some services depend on other services. Some such integrations are optional, but all services depend on 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 +sufficient. + +### 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 127.0.0.1:9123"` + +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:
In addition to the runtime dependencies of our packages, building packages from source requires additional build-time dependencies:
+ +* `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
Not that I care, but this is missing dispatch. Should also probably be alpha sorted.
+ # 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 +
Add: Hacking on these projects can be somewhat subjective and flexible. You may want or need to modify or skip some of these instructions to suit your individual needs.
+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 +`SRHT_PATH`: + + 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: + + make + cd api && go build
Following adnano's changes to Makefiles in git.sr.ht to support building the API, can you make these changes uniform across all projects with a GraphQL API and update this line in the docs?
+ +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://127.0.0.1`. Additionally, set +`global-domain=127.0.0.1` to ensure cookies are created with the correct +parameters.
I would advise reading the config here, it has instructions written into the comments.
+ +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=http://127.0.0.1:5000` (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 + ./metasrht-initdb + +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. -- 2.35.1
If you are ok with this pattern I will gradually add the instructions for the other services.
Overall LGTM
-1 to writing documentation for other projects