@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Configuration Guide
2@group config
3
4This document contains basic configuration instructions for Phorge.
5
6= Prerequisites =
7
8This document assumes you've already installed all the components you need.
9If you haven't, see @{article:Installation Guide}.
10
11The next steps are:
12
13 - Configure your webserver (Apache, nginx, or lighttpd).
14 - Configure the databases.
15 - Access Phorge with your browser.
16 - Follow the instructions to complete setup.
17
18= Webserver: Configuring Apache =
19
20NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll
21down to their sections.
22
23Get Apache running and verify it's serving a test page. Consult the Apache
24documentation for help. Make sure `mod_php` and `mod_rewrite` are enabled,
25and `mod_ssl` if you intend to set up SSL.
26
27If you haven't already, set up a domain name to point to the host you're
28installing on. You can either install Phorge on a subdomain (like
29phorge.example.com) or an entire domain, but you can not install it in
30some subdirectory of an existing website. Navigate to whatever domain you're
31going to use and make sure Apache serves you something to verify that DNS
32is correctly configured.
33
34NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
35'http://example/'. Some web browsers will not set cookies otherwise.
36
37Now create a VirtualHost entry for Phorge. It should look something like
38this:
39
40 name=httpd.conf
41 <VirtualHost *>
42 # Change this to the domain which points to your host.
43 ServerName phorge.example.com
44
45 # Change this to the path where you put 'phorge' when you checked it
46 # out from the upstream when following the Installation Guide.
47 #
48 # Make sure you include "/webroot" at the end!
49 DocumentRoot /path/to/phorge/webroot
50
51 RewriteEngine on
52 RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA,UnsafeAllow3F]
53 </VirtualHost>
54
55If Apache isn't currently configured to serve documents out of the directory
56where you put Phorge, you may also need to add `<Directory />` section. The
57syntax for this section depends on which version of Apache you're running.
58(If you don't know, you can usually figure this out by running `httpd -v`.)
59For Apache versions older than 2.4, use this:
60
61 name="Apache Older Than 2.4"
62 <Directory "/path/to/phorge/webroot">
63 Order allow,deny
64 Allow from all
65 </Directory>
66
67For Apache versions 2.4 and newer, use this:
68
69 name="Apache 2.4 and Newer"
70 <Directory "/path/to/phorge/webroot">
71 Require all granted
72 </Directory>
73
74After making your edits, restart Apache, then continue to "Setup" below.
75
76= Webserver: Configuring nginx =
77
78NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll
79to their sections.
80
81For nginx, use a configuration like this:
82
83 name=nginx.conf
84 server {
85 server_name phorge.example.com;
86 root /path/to/phorge/webroot;
87
88 location / {
89 index index.php;
90 rewrite ^/(.*)$ /index.php?__path__=/$1 last;
91 }
92
93 location /index.php {
94 fastcgi_pass localhost:9000;
95 fastcgi_index index.php;
96
97 #required if PHP was built with --enable-force-cgi-redirect
98 fastcgi_param REDIRECT_STATUS 200;
99
100 #variables to make the $_SERVER populate in PHP
101 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
102 fastcgi_param QUERY_STRING $query_string;
103 fastcgi_param REQUEST_METHOD $request_method;
104 fastcgi_param CONTENT_TYPE $content_type;
105 fastcgi_param CONTENT_LENGTH $content_length;
106
107 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
108
109 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
110 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
111
112 fastcgi_param REMOTE_ADDR $remote_addr;
113 }
114 }
115
116Restart nginx after making your edits, then continue to "Setup" below.
117
118= Webserver: Configuring lighttpd =
119
120NOTE: Follow these instructions to use lighttpd. To use Apache or nginx, scroll
121up to their sections.
122
123For lighttpd, add a section like this to your lighttpd.conf:
124
125 $HTTP["host"] =~ "phorge(\.example\.com)?" {
126 server.document-root = "/path/to/phorge/webroot"
127 url.rewrite-once = (
128 # This simulates QSA ("query string append") mode in apache
129 "^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
130 "^(/.*)$" => "/index.php?__path__=$1",
131 )
132 }
133
134You should also ensure the following modules are listed in your
135server.modules list:
136
137 mod_fastcgi
138 mod_rewrite
139
140Finally, you should run the following commands to enable php support:
141
142 $ sudo apt-get install php-cgi # for Ubuntu; other distros should be similar
143 $ sudo lighty-enable-mod fastcgi-php
144
145Restart lighttpd after making your edits, then continue below.
146
147
148Load Balancer Health Checks
149===========================
150
151If you're using a load balancer in front of your webserver, you can configure
152it to perform health checks using the path `/status/`.
153
154
155= Setup =
156
157Now, navigate to whichever subdomain you set up. You should see instructions to
158continue setup. The rest of this document contains additional instructions for
159specific setup steps.
160
161When you resolve any issues and see the welcome screen, enter credentials to
162create your initial administrator account. After you log in, you'll want to
163configure how other users will be able to log in or register -- until you do,
164no one else will be able to sign up or log in. For more information, see
165@{article:Configuring Accounts and Registration}.
166
167= Storage: Configuring MySQL =
168
169During setup, you'll need to configure MySQL. To do this, get MySQL running and
170verify you can connect to it. Consult the MySQL documentation for help. When
171MySQL works, you need to load the Phorge schemata into it. To do this, run:
172
173 phorge/ $ ./bin/storage upgrade
174
175If your configuration uses an unprivileged user to connect to the database, you
176may have to override the default user so the schema changes can be applied with
177root or some other admin user:
178
179 phorge/ $ ./bin/storage upgrade --user <user> --password <password>
180
181You can avoid the prompt the script issues by passing the `--force` flag (for
182example, if you are scripting the upgrade process).
183
184 phorge/ $ ./bin/storage upgrade --force
185
186NOTE: When you update Phorge, run `storage upgrade` again to apply any
187new updates.
188
189= Next Steps =
190
191Continue by:
192
193 - setting up your admin account and login/registration with
194 @{article:Configuring Accounts and Registration}; or
195 - understanding advanced configuration topics with
196 @{article:Configuration User Guide: Advanced Configuration}; or
197 - configuring an alternate file domain with
198 @{article:Configuring a File Domain}; or
199 - configuring a preamble script to set up the environment properly behind a
200 load balancer, or adjust rate limiting with
201 @{article:Configuring a Preamble Script}; or
202 - configuring where uploaded files and attachments will be stored with
203 @{article:Configuring File Storage}; or
204 - configuring Phorge so it can send mail with
205 @{article:Configuring Outbound Email}; or
206 - configuring inbound mail with @{article:Configuring Inbound Email}; or
207 - importing repositories with @{article:Diffusion User Guide}; or
208 - learning about daemons with @{article:Managing Daemons with phd}; or
209 - learning about notification with
210 @{article:Notifications User Guide: Setup and Configuration}; or
211 - configuring backups with
212 @{article:Configuring Backups and Performing Migrations}; or
213 - contributing to Phorge with @{article:Contributor Introduction}.