No OneTemporary
Actions

Size

15 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/docs/book/user.book b/src/docs/book/user.book
	index 449acd4ffc..b5b6dac7b1 100644
	--- a/src/docs/book/user.book
	+++ b/src/docs/book/user.book
	@@ -1,42 +1,42 @@
	{
	"name": "phorge",
	- "title": "Phorge User Documentation",
	+ "title": "Phorge Administrator and User Documentation",
	"short": "User Docs",
	"preface": "Instructions for installing, configuring, and using Phorge.",
	"root": "../../../",
	"uri.source":
	"https://we.phorge.it/diffusion/P/browse/master/%f$%l",
	"rules": {
	"(\\.diviner$)": "DivinerArticleAtomizer"
	},
	"exclude": [
	"(^externals/)",
	"(^resources/)",
	"(^scripts/)",
	"(^src/docs/contributor/)",
	"(^src/docs/flavor/)",
	"(^src/docs/tech/)",
	"(^support/)",
	"(^webroot/rsrc/externals/)"
	],
	"groups": {
	"intro": {
	"name": "Introduction"
	},
	"config": {
	"name": "Configuration"
	},
	"userguide": {
	"name": "Application User Guides"
	},
	"conduit": {
	"name": "API Documentation"
	},
	"cluster": {
	"name": "Cluster Configuration"
	},
	"fieldmanual": {
	"name": "Field Manuals"
	}
	}
	}
	diff --git a/src/docs/user/configuration/configuration_guide.diviner b/src/docs/user/configuration/configuration_guide.diviner
	index 7798ff0e0b..1fde967a95 100644
	--- a/src/docs/user/configuration/configuration_guide.diviner
	+++ b/src/docs/user/configuration/configuration_guide.diviner
	@@ -1,212 +1,213 @@
	@title Configuration Guide
	@group config

	This document contains basic configuration instructions for Phorge.

	= Prerequisites =

	This document assumes you've already installed all the components you need.
	If you haven't, see @{article:Installation Guide}.

	The next steps are:

	- Configure your webserver (Apache, nginx, or lighttpd).
	+ - Configure the databases.
	- Access Phorge with your browser.
	- Follow the instructions to complete setup.

	= Webserver: Configuring Apache =

	NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll
	down to their sections.

	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 Phorge on a subdomain (like
	phorge.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.

	NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
	'http://example/'. Some web browsers will not set cookies otherwise.

	Now create a VirtualHost entry for Phorge. It should look something like
	this:

	name=httpd.conf
	<VirtualHost *>
	# Change this to the domain which points to your host.
	ServerName phorge.example.com

	# Change this to the path where you put 'phorge' when you checked it
	# out from the upstream when following the Installation Guide.
	#
	# Make sure you include "/webroot" at the end!
	DocumentRoot /path/to/phorge/webroot

	RewriteEngine on
	RewriteRule ^(.*)$ /index.php?__path__=$1 [B,L,QSA]
	</VirtualHost>

	If Apache isn't currently configured to serve documents out of the directory
	where you put Phorge, you may also need to add `<Directory />` section. The
	syntax for this section depends on which version of Apache you're running.
	(If you don't know, you can usually figure this out by running `httpd -v`.)
	For Apache versions older than 2.4, use this:

	name="Apache Older Than 2.4"
	<Directory "/path/to/phorge/webroot">
	Order allow,deny
	Allow from all
	</Directory>

	For Apache versions 2.4 and newer, use this:

	name="Apache 2.4 and Newer"
	<Directory "/path/to/phorge/webroot">
	Require all granted
	</Directory>

	After making your edits, restart Apache, then continue to "Setup" below.

	= Webserver: Configuring nginx =

	NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll
	to their sections.

	For nginx, use a configuration like this:

	name=nginx.conf
	server {
	server_name phorge.example.com;
	root /path/to/phorge/webroot;

	location / {
	index index.php;
	rewrite ^/(.*)$ /index.php?__path__=/$1 last;
	}

	location /index.php {
	fastcgi_pass localhost:9000;
	fastcgi_index index.php;

	#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;
	}
	}

	Restart nginx after making your edits, then continue to "Setup" below.

	= Webserver: Configuring lighttpd =

	NOTE: Follow these instructions to use lighttpd. To use Apache or nginx, scroll
	up to their sections.

	For lighttpd, add a section like this to your lighttpd.conf:

	$HTTP["host"] =~ "phorge(\.example\.com)?" {
	server.document-root = "/path/to/phorge/webroot"
	url.rewrite-once = (
	# This simulates QSA ("query string append") mode in apache
	"^(/[^?])\?(.)" => "/index.php?__path__=$1&$2",
	"^(/.*)$" => "/index.php?__path__=$1",
	)
	}

	You should also ensure the following modules are listed in your
	server.modules list:

	mod_fastcgi
	mod_rewrite

	Finally, you should run the following commands to enable php support:

	$ sudo apt-get install php5-cgi # for Ubuntu; other distros should be similar
	$ sudo lighty-enable-mod fastcgi-php

	Restart lighttpd after making your edits, then continue below.


	Load Balancer Health Checks
	===========================

	If you're using a load balancer in front of your webserver, you can configure
	it to perform health checks using the path `/status/`.


	= Setup =

	Now, navigate to whichever subdomain you set up. You should see instructions to
	continue setup. The rest of this document contains additional instructions for
	specific setup steps.

	When you resolve any issues and see the welcome screen, enter credentials to
	create your initial administrator account. After you log in, you'll want to
	configure how other users will be able to log in or register -- until you do,
	no one else will be able to sign up or log in. For more information, see
	@{article:Configuring Accounts and Registration}.

	= Storage: Configuring MySQL =

	During setup, you'll need to configure MySQL. To do this, get MySQL running and
	verify you can connect to it. Consult the MySQL documentation for help. When
	MySQL works, you need to load the Phorge schemata into it. To do this, run:

	phorge/ $ ./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:

	phorge/ $ ./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).

	phorge/ $ ./bin/storage upgrade --force

	NOTE: When you update Phorge, run `storage upgrade` again to apply any
	new updates.

	= Next Steps =

	Continue by:

	- setting up your admin account and login/registration with
	@{article:Configuring Accounts and Registration}; or
	- understanding advanced configuration topics with
	@{article:Configuration User Guide: Advanced Configuration}; or
	- configuring an alternate file domain with
	@{article:Configuring a File Domain}; or
	- configuring a preamble script to set up the environment properly behind a
	load balancer, or adjust rate limiting with
	@{article:Configuring a Preamble Script}; or
	- configuring where uploaded files and attachments will be stored with
	@{article:Configuring File Storage}; or
	- configuring Phorge 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
	- learning about notification with
	@{article:Notifications User Guide: Setup and Configuration}; or
	- configuring backups with
	@{article:Configuring Backups and Performing Migrations}; or
	- contributing to Phorge with @{article:Contributor Introduction}.
	diff --git a/src/docs/user/installation_guide.diviner b/src/docs/user/installation_guide.diviner
	index ded0e4c93a..6db0df4d7c 100644
	--- a/src/docs/user/installation_guide.diviner
	+++ b/src/docs/user/installation_guide.diviner
	@@ -1,133 +1,142 @@
	@title Installation Guide
	@group intro

	This document contains basic install instructions to get Phorge up and
	running.

	Overview
	========

	Phorge is a LAMP (Linux, Apache, MySQL, PHP) application. To install
	Phorge, you will need:

	- a normal computer to install it on (shared hosts and unusual environments
	are not supported) running some flavor of Linux or a similar OS;
	- a domain name (like `phorge.example.com`);
	- basic sysadmin skills;
	- Apache, nginx, or another webserver;
	- - PHP, MySQL, and Git.
	+ - PHP;
	+ - MySQL (you will need a server with multiple databases);
	+ - git

	The remainder of this document details these requirements.

	+You may be interested also in preparing these optional stuff:
	+
	+ - have valid SMTP parameters for outgoing email notifications;
	+ - having nothing listening on port 22, to then setup a SSH+git server
	+
	Installation Requirements
	=========================

	You will need a computer. Options include:

	- A Normal Computer: This is strongly recommended. Many installs use a VM
	in EC2. Phorge installs properly and works well on a normal computer.
	- A Shared Host: This may work, but is not recommended. Many shared
	hosting environments have restrictions which prevent some of Phorge's
	features from working. Consider using a normal computer instead. We do not
	support shared hosts.
	- A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.:
	Although you may be able to install Phorge on specialized hardware, it
	is unlikely to work well and will be difficult for us to support. Strongly
	consider using a normal computer instead. We do not support specialized
	hardware.
	- A Toaster, Car, Firearm, Thermostat, etc.: Yes, many modern devices now
	have embedded computing capability. We live in interesting times. However,
	you should not install Phorge on these devices. Instead, install it on
	a normal computer. We do not support installing on noncomputing devices.

	To install the Phorge server software, you will need an **operating
	system on your normal computer which is not Windows**. Note that the
	command line interface //does// work on Windows, and you can //use//
	Phorge from any operating system with a web browser. However, the server
	software does not run on Windows. It does run on most other operating systems,
	so choose one of these instead:

	- Linux: Most installs use Linux.
	- Mac OS X: Mac OS X is an acceptable flavor of Linux.
	- FreeBSD: While FreeBSD is certainly not a flavor of Linux, it is a fine
	operating system possessed of many desirable qualities, and Phorge will
	install and run properly on FreeBSD.
	- Solaris, etc.: Other systems which look like Linux and quack like Linux
	will generally work fine, although we may suffer a reduced ability to
	support and resolve issues on unusual operating systems.

	Beyond an operating system, you will need a webserver.

	- Apache: Many installs use Apache + `mod_php`.
	- nginx: Many installs use nginx + `php-fpm`.
	- lighttpd: `lighttpd` is less popular than Apache or nginx, but it
	works fine.
	- Other: Other webservers which can run PHP are also likely to work fine,
	although these installation instructions will not cover how to set them up.
	- PHP Builtin Server: Phorge will not work with the builtin
	webserver because Phorge depends on making requests to itself on some
	workflows, and the builtin webserver is single-threaded.

	You will also need:

	- MySQL: You need MySQL. We strongly recommend MySQL 5.5 or newer.
	- - PHP: You need PHP 5.5 or newer.
	+ You will need a server with multiple databases.
	+ - PHP: You need PHP 5.5 or newer. Note that PHP 8.1 and above are not
	+ fully supported.

	You'll probably also need a domain name. In particular, you should read this
	note:

	NOTE: Phorge must be installed on an entire domain. You can not install it
	to a path on an existing domain, like `example.com/phorge/`. Instead,
	install it to an entire domain or subdomain, like `phorge.example.com`.

	Level Requirements
	==================

	To install and administrate Phorge, you'll need to be comfortable with
	common system administration skills. For example, you should be familiar with
	using the command line, installing software on your operating system of choice,
	working with the filesystem, managing processes, dealing with permissions,
	editing configuration files, and setting environment variables.

	If you aren't comfortable with these skills, you can still try to perform an
	install. The install documentation will attempt to guide you through what you
	need to know. However, if you aren't very familiar or comfortable with using
	this set of skills to troubleshoot and resolve problems, you may encounter
	issues which you have substantial difficulty working through.

	We assume users installing and administrating Phorge are comfortable with
	common system administration skills and concepts. If you aren't, proceed at
	your own risk and expect that your skills may be tested.

	Installing Required Components
	==============================

	Here's a general description of what you need to install:

	- git (usually called "git" in package management systems)
	- Apache (usually "httpd" or "apache2") (or nginx)
	- - MySQL Server (usually "mysqld" or "mysql-server")
	+ - MySQL Server (usually "mysqld" or "mysql-server" or "mariadb-server")
	- PHP (usually "php")
	- Required PHP extensions: mbstring, iconv, mysql (or mysqli), curl, pcntl
	(these might be something like "php-mysql" or "php5-mysqlnd")
	- Optional PHP extensions: gd

	If you already have LAMP setup, you've probably already got everything you need.
	It may also be helpful to refer to the install scripts above, even if they don't
	work for your system.

	Now that you have all that stuff installed, grab Phorge and its
	dependencies:

	$ cd somewhere/ # pick some install directory
	somewhere/ $ git clone https://we.phorge.it/source/arcanist.git
	somewhere/ $ git clone https://we.phorge.it/source/phorge.git

	Next Steps
	==========

	Continue by:

	- configuring Phorge with the @{article:Configuration Guide}; or
	- learning how to keep Phorge up to date with
	@{article:Upgrading Phorge}.

File Metadata

Mime Type: text/x-diff
Expires: Sun, Nov 24, 4:01 AM (1 d, 12 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 977
Default Alt Text: (15 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions