Homec4science
Diffusion Phabricator (feature/better-testing) Browse

phab/src/docs/configuration/configuration_guide.diviner
087cc0808a34feature/better-testing

Last Change
Raw File

configuration_guide.diviner
View Options

@title Configuration Guide
@group config
This document contains basic configuration instructions for Phabricator.
= Prerequisites =
This document assumes you've already installed all the components you need.
If you haven't, see @{article:Installation Guide}.
= Configuring Phabricator =
Create a new file here:
path/to/phabricator/conf/custom/myconfig.conf.php
...where ##myconfig## is some name which identifies your installation. Put this
in the file:
name=myconfig.conf.php, lang=php
<?php
return array(
// Important! This will put Phabricator into setup mode to help you
// configure things.
'phabricator.setup' => true,
// This will be the base domain for your install, and must be configured.
// Use "https://" if you have SSL. See below for some notes.
'phabricator.base-uri' => 'http://phabricator.example.com/',
// Connection information for MySQL.
'mysql.host' => 'localhost',
'mysql.user' => 'root',
'mysql.pass' => 'trustno1hunter2',
// Basic email domain configuration.
'metamta.default-address' => 'noreply@phabricator.example.com',
'metamta.domain' => 'phabricator.example.com',
// NOTE: Check default.conf.php for detailed explanations of all the
// configuration options, including these.
) + phabricator_read_config_file('production');
For the last line, you can also use ##'development'## instead of
##'production'## if you are planning to develop Phabricator itself. This will
turn on some debugging features.
= PHABRICATOR_ENV Environment Variable =
When running Phabricator scripts, they will ask you to set the `PHABRICATOR_ENV`
environment variable to point at your config. If you put your script in
`custom/myconfig.conf.php`, you can identify the config with
`custom/myconfig`, like this:
$ PHABRICATOR_ENV=custom/myconfig ./some_phabricator_command
NOTE: Make sure you put 'PHABRICATOR_ENV=...' at the beginning of the line, not
in the middle. The shell won't parse environmental variables declared after the
command. You can also ##export PHABRICATOR_ENV=...## in your ~/.bashrc or
~/.profile or similar, depending on which shell you use and how your system is
configured.
= Storage: Configuring MySQL =
Get MySQL running and verify you can connect to it. Consult the MySQL
documentation for help. When MySQL works, you need to load the Phabricator
schemata into it. To do this, run:
phabricator/ $ ./bin/storage upgrade
If your configuration uses an unprivileged user to connect to the database, you
may have to override the default user so the schema changes can be applied with
root or some other admin user:
phabricator/ $ ./bin/storage upgrade --user <user> --password <password>
You can avoid the prompt the script issues by passing the ##--force## flag (for
example, if you are scripting the upgrade process).
phabricator/ $ ./bin/storage upgrade --force
NOTE: When you update Phabricator, run `storage upgrade` again to apply any
new updates.
= Webserver: Configuring Apache =
Get Apache running and verify it's serving a test page. Consult the Apache
documentation for help. Make sure ##mod_php## and ##mod_rewrite## are enabled,
and ##mod_ssl## if you intend to set up SSL.
If you haven't already, set up a domain name to point to the host you're
installing on. You can either install Phabricator on a subdomain (like
phabricator.example.com) or an entire domain, but you can not install it in
some subdirectory of an existing website. Navigate to whatever domain you're
going to use and make sure Apache serves you something to verify that DNS
is correctly configured.
Now, either create a VirtualHost entry (to put Phabricator on a subdomain)
or edit the Directory entry for the DocumentRoot. It should look something like
this:
name=httpd.conf
<VirtualHost *>
# Change this to the domain which points to your host, i.e. the domain
# you set as "phabricator.base-uri".
ServerName phabricator.example.com
# Change this to the path where you put 'phabricator' when you checked it
# out from github when following the Installation Guide.
DocumentRoot /path/to/phabricator/webroot
RewriteEngine on
RewriteRule ^/rsrc/(.*) - [L,QSA]
RewriteRule ^/favicon.ico - [L,QSA]
RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
# This will use the config file you set up in the previous step. If you
# called it something other than 'myconfig', put that here.
SetEnv PHABRICATOR_ENV custom/myconfig
</VirtualHost>
Continue to "Setup" below.
= Webserver: Configuring nginx =
For nginx, use a configuration like this:
name=nginx.conf
server {
server_name phabricator.example.com;
root /path/to/phabricator/webroot;
try_files $uri $uri/ /index.php;
location / {
index index.php;
if ( !-f $request_filename )
{
rewrite ^/(.*)$ /index.php?__path__=/$1 last;
break;
}
}
location ~ \.php$ {
fastcgi_pass localhost:9000;
fastcgi_index index.php;
#custom environment variable
fastcgi_param PHABRICATOR_ENV "custom/myconfig";
#required if PHP was built with --enable-force-cgi-redirect
fastcgi_param REDIRECT_STATUS 200;
#variables to make the $_SERVER populate in PHP
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
fastcgi_param REMOTE_ADDR $remote_addr;
}
}
= Setup =
Now, restart your webserver and navigate to whichever subdomain you set up. You
should either see the Phabricator setup screen, which is a simple text page that
looks something like this:
PHABRICATOR SETUP
This setup mode will guide you through setting up your Phabricator
configuration.
>>> REQUIRED PHP EXTENSIONS ------------------------------------------------
...
If you see this, you're in good shape. Follow the instructions and correct any
problems setup detects. If you don't see it but you do see a useful error
message, try to fix that. If neither of these cover you, something is wrong.
If you can't figure it out, come get help in IRC or on the mailing list (see
http://phabricator.org/ for links).
= Configuring Phabricator =
Now that basic setup is complete, you should configure Phabricator for your
installation. Phabricator configuration options which control how the
applications behave are documented here:
/path/to/phabricator/conf/default.conf.php
There are several builtin configurations:
- ##default.conf.php##: root configuration, lists every configuration option
and sets some default for it. Look in this file to figure out what you can
configure.
- ##development.conf.php##: pulls in ##default.conf.php##, but overrides some
configuration options to better values for doing development on Phabricator.
You probably don't need to even look at this file unless you're making
changes to Phabricator itself.
- ##production.conf.php##: pulls in ##default.conf.php##, but overrides some
configuration options to provide better values for a production install.
To actually configure your install, edit your ##custom/myconfig.conf.php## file
and override values from either the ##'production'## or ##'development'##
configurations. You should not edit the builtin configurations directly because
that will make upgrading Phabricator more difficult in the future.
= Next Steps =
Continue by:
- setting up your admin account and login/registration with
@{article:Configuring Accounts and Registration}; or
- configuring where uploaded fils and attachments will be stored with
@{article:Configuring File Storage}; or
- configuring Phabricator so it can send mail with
@{article:Configuring Outbound Email}; or
- configuring inbound mail with @{article:Configuring Inbound Email}; or
- importing repositories with @{article:Diffusion User Guide}; or
- learning about daemons with @{article:Managing Daemons with phd}; or
- contributing to Phabricator with @{article:Contributor Introduction}.
c4science · Help