1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
---
title: Installation
---
Installation of sr.ht web services uses a mostly consistent procedure across the
network. Specific details to each service are available on each service's
installation page:
- [builds.sr.ht](/builds.sr.ht/installation.md)
- [dispatch.sr.ht](/todo.sr.ht/installation.md)
- [git.sr.ht](/git.sr.ht/installation.md)
- [hg.sr.ht](/hg.sr.ht/installation.md)
- [lists.sr.ht](/lists.sr.ht/installation.md)
- [man.sr.ht](/man.sr.ht/installation.md)
- [meta.sr.ht](/meta.sr.ht/installation.md)
- [paste.sr.ht](/todo.sr.ht/installation.md)
- [todo.sr.ht](/todo.sr.ht/installation.md)
All sr.ht sysadmins are encouraged to subscribe to the
[sr.ht-admins](https://lists.sr.ht/~sircmpwn/sr.ht-admins) mailing list, a
low-volume list of sysadmin-oriented announcements regarding breaking changes,
security vulnerabilities, and so on.
General installation instructions follow.
# Packages
sr.ht provides a number of Linux distribution package repositories for your
use. For details specific to your distribution, see [packages.md](/packages.md).
Even if you wish to install sr.ht services from source, your distribution may
not include some of our dependencies and using our package repositories is
recommended.
Installation from packages will also give you distro-specific daemon services
and will handle database migrations automatically during system updates.
# Development
Please send patches to [sr.ht-dev](https://lists.sr.ht/~sircmpwn/sr.ht-dev).
This is also the right place to ask questions about the code. Also check out
[hacking on sr.ht](#hacking-on-srht) for an amended installation procedure for
local hacking.
# Prerequisites
You will need at least:
- A PostgreSQL server
- A Redis server
- A mail server
- A cron daemon
In order to use most sr.ht services.
# sr.ht core
sr.ht core is a Python package that provides shared functionality across all
sr.ht services. It also contains the default templates and stylesheets that give
sr.ht a consistent look and feel.
The core package is listed as a dependency of the official `*.sr.ht` packages,
so installing it explicitly is not necessary if you are using our package
repositories. If you are not using our packages, obtain the [source
code](https://git.sr.ht/~sircmpwn/srht), initialize submodules and install it
like a typical Python package (`./setup.py install --prefix=/usr`). You will
need to install its dependencies beforehand, for an up-to-date list see [the
package](https://git.sr.ht/~sircmpwn/sr.ht-pkgbuilds/tree/master/python-srht/PKGBUILD).
# Package Installation
Packages are named as you would expect: meta.sr.ht is called `meta.sr.ht`. On
package managers where dots are not permitted in package names, dashes are used.
Underscores are used on systems where dashes are not permitted.
If installing from source, see [the
packages](https://git.sr.ht/~sircmpwn/sr.ht-pkgbuilds) for an up-to-date list of
dependencies and install it like any other Python package: `./setup.py install
--prefix=/usr`. When installing from source, daemon service files are not
provided; you must write one appropriate to your system.
# Site Configuration
The config file for all sr.ht sites is located at `/etc/sr.ht/config.ini`. Each
site provides an example configuration in `config.example.ini`, which includes
the global (shared) config options, and any options specific to its operation.
You should merge the configs of each sr.ht site you want to run.
# Database Configuration
Start by setting your config.ini's connection string to a superuser, then run
the following commands to create the initial schema:
$ python3
>>> from [module].app import db
>>> db.create()
Substitute `[module]` for the specific application's module, such as `metasrht`
or `buildsrht`. When complete, you may update your connection string to use a
less privileged user.
## Schema Upgrades
We use [alembic](http://alembic.zzzcomputing.com/en/latest/) to manage schema
migrations. We source your alembic config from your main sr.ht `config.ini` - no
need to write an `alembic.ini` file. Run `<service>-migrate stamp head` once to
tell alembic the schema is up-to-date. Future upgrades will be managed
automatically by the package, or if you're using the source code you can run
`<service>-migrate upgrade head` when you pull the latest version down.
## Becoming admin
After setting up meta.sr.ht and registering yourself a user account, you can
give that account admin permissions:
$ python3
>>> from metasrht.app import db, User, UserType
>>> u = User.query.filter_by(username='[your username]').one()
>>> u.user_type = UserType.admin
>>> User.query.session.commit()
# Compile static assets
This step is only necessary for users configuring sr.ht from source. Run `make`
in the root of the repository to compile static assets. `setup.py` will usually
do this for you.
# Start the service
A service file is included in the packages and uses the same name as the
package. On Arch Linux, for example, you can run `systemctl enable --now
meta.sr.ht` to start up meta.sr.ht, or `rc-update add meta.sr.ht && service
meta.sr.ht start` on Alpine. The service will be running at the port specified
in its config file, and you must now prepare to proxy to it.
# Proxy configuration
The exact nginx configuration you use will vary depending on your needs. Here is
an example for meta.sr.ht:
server {
listen 80;
server_name meta.sr.ht;
location / {
return 302 https://$server_name$request_uri;
}
location ^~ /.well-known {
root /var/www;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name meta.sr.ht;
client_max_body_size 100M;
ssl_certificate /var/lib/acme/live/meta.sr.ht/fullchain;
ssl_certificate_key /var/lib/acme/live/meta.sr.ht/privkey;
ssl_trusted_certificate /var/lib/acme/live/meta.sr.ht/fullchain;
location / {
proxy_pass http://127.0.0.1:5002;
}
location /static {
root /usr/lib/python3.6/site-packages/metasrht;
}
location ^~ /.well-known {
root /var/www;
}
}
Once the proxy is configured, you should be able to access your new service.
# OAuth configuration
For services other than meta.sr.ht, you have to create and configure an OAuth
client before users can log into your service. To do that, visit your profile
on your meta.sr.ht instance, select the OAuth tab and register a new client.
Append the path `/oauth/callback` to the URL of your service instance and
choose this value as the base redirect URI (for example
`https://git.sr.ht/oauth/callback`). Update your configuration file with the
client ID and secret.
You then need to configure that client as "preauthorized", i.e. first-party.
This skips the OAuth consent screen that third-party applications are subject to
and enables some extra API features. Log into the meta.sr.ht database and run
the following query (adjusting the client ID as appropriate):
```sql
update oauthclient set preauthorized = true where client_id = 'your client ID';
```
Now you should be able to log into your new service.
# Hacking on sr.ht
If you just want to get the codebase running to hack on it, follow these steps:
1. [Prerequisites](#prerequisites)
2. [sr.ht core](#srht-core), however, you can simply clone it somewhere and add
it to your Python path. Also export `SRHT_PATH=/path/to/sr.ht-core` to use
your development repository for generating static assets.
3. [Site configuration](#site-configuration), but you can just put `config.ini`
in the working directory and sr.ht will read it there.
4. [Database configuration](#database-configuration)
5. [Compile static assets](#compile-static-assets)
6. `./run.py` will start the development server.
|
