mirror of https://github.com/postgres/postgres
Up to now, our distribution tarballs have included a plain-text form of the installation.sgml chapter. The rationale for that was that a recipient might not have either ready internet access or HTML-viewing tools; a theory that seems downright quaint today. Maintaining the ability to generate this file is not without cost, because it puts special requirements on installation.sgml that are often overlooked. Moreover, we are moving in the direction of making our distribution tarballs be pure git snapshots for traceability/reproducibility reasons; including generated files doesn't fit into that plan. Hence, let's just drop INSTALL and remove the infrastructure for generating it. The top-level README will now recommend visiting our website to see the installation instructions. As a useful side-effect, we can get rid of README.git which has provoked confusion. Discussion: https://postgr.es/m/20231220114927.faccqqprmuyrzdip@alap3.anarazel.de Discussion: https://postgr.es/m/e07408d9-e5f2-d9fd-5672-f53354e9305e@eisentraut.orgpull/151/head
Tom Lane
2 years ago
parent
8ddf9c1dc0
commit
e2b73f4a4d
@ -1,14 +0,0 @@ |
||||
(This file does not appear in release tarballs.) |
||||
|
||||
In a release or snapshot tarball of PostgreSQL, a documentation file named |
||||
INSTALL will appear in this directory. However, this file is not stored in |
||||
git and so will not be present if you are using a git checkout. |
||||
|
||||
If you are using a git checkout, you can view the most recent installation |
||||
instructions at: |
||||
https://www.postgresql.org/docs/devel/installation.html |
||||
|
||||
Users compiling from git will also need compatible versions of Bison, Flex, |
||||
and Perl, as discussed in the install documentation. These programs are not |
||||
needed when using a tarball, since the files they are needed to build are |
||||
already present in the tarball. (On Windows, however, you need Perl anyway.) |
||||
@ -1,170 +0,0 @@ |
||||
<?xml version="1.0"?> |
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
||||
<!-- |
||||
This file contains the stand-alone installation instructions that end up in |
||||
the INSTALL file. This document stitches together parts of the installation |
||||
instructions in the main documentation with some material that only appears |
||||
in the stand-alone version. |
||||
--> |
||||
<article id="installation"> |
||||
<title><productname>PostgreSQL</productname> Installation from Source Code</title> |
||||
|
||||
<!-- This text replaces the introductory text of installation.sgml --> |
||||
<para> |
||||
This document describes the installation of |
||||
<productname>PostgreSQL</productname> using this source code distribution. |
||||
</para> |
||||
|
||||
<para> |
||||
If you are building <productname>PostgreSQL</productname> for Microsoft |
||||
Windows, read this document if you intend to build with MinGW or Cygwin; |
||||
but if you intend to build with Microsoft's <productname>Visual |
||||
C++</productname>, see the main documentation instead. |
||||
</para> |
||||
|
||||
<xi:include href="postgres-full.xml" xpointer="install-requirements" xmlns:xi="http://www.w3.org/2001/XInclude"/> |
||||
<xi:include href="postgres-full.xml" xpointer="install-make" xmlns:xi="http://www.w3.org/2001/XInclude"/> |
||||
<xi:include href="postgres-full.xml" xpointer="install-post" xmlns:xi="http://www.w3.org/2001/XInclude"/> |
||||
|
||||
<sect1 id="install-getting-started"> |
||||
<title>Getting Started</title> |
||||
|
||||
<para> |
||||
The following is a quick summary of how to get <productname>PostgreSQL</productname> up and |
||||
running once installed. The main documentation contains more information. |
||||
</para> |
||||
|
||||
<procedure> |
||||
<step> |
||||
<para> |
||||
Create a user account for the <productname>PostgreSQL</productname> |
||||
server. This is the user the server will run as. For production |
||||
use you should create a separate, unprivileged account |
||||
(<quote>postgres</quote> is commonly used). If you do not have root |
||||
access or just want to play around, your own user account is |
||||
enough, but running the server as root is a security risk and |
||||
will not work. |
||||
<screen><userinput>adduser postgres</userinput></screen> |
||||
</para> |
||||
</step> |
||||
|
||||
<step> |
||||
<para> |
||||
Create a database installation with the <command>initdb</command> |
||||
command. To run <command>initdb</command> you must be logged in to your |
||||
<productname>PostgreSQL</productname> server account. It will not work as |
||||
root. |
||||
<screen>root# <userinput>mkdir /usr/local/pgsql/data</userinput> |
||||
root# <userinput>chown postgres /usr/local/pgsql/data</userinput> |
||||
root# <userinput>su - postgres</userinput> |
||||
postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</userinput></screen> |
||||
</para> |
||||
|
||||
<para> |
||||
The <option>-D</option> option specifies the location where the data |
||||
will be stored. You can use any path you want, it does not have |
||||
to be under the installation directory. Just make sure that the |
||||
server account can write to the directory (or create it, if it |
||||
doesn't already exist) before starting <command>initdb</command>, as |
||||
illustrated here. |
||||
</para> |
||||
</step> |
||||
|
||||
<step> |
||||
<para> |
||||
At this point, if you did not use the <command>initdb</command> <literal>-A</literal> |
||||
option, you might want to modify <filename>pg_hba.conf</filename> to control |
||||
local access to the server before you start it. The default is to |
||||
trust all local users. |
||||
</para> |
||||
</step> |
||||
|
||||
<step> |
||||
<para> |
||||
The previous <command>initdb</command> step should have told you how to |
||||
start up the database server. Do so now. The command should look |
||||
something like: |
||||
<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start</programlisting> |
||||
</para> |
||||
|
||||
<para> |
||||
To stop a server running in the background you can type: |
||||
<programlisting>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data stop</programlisting> |
||||
</para> |
||||
</step> |
||||
|
||||
<step> |
||||
<para> |
||||
Create a database: |
||||
<screen><userinput>/usr/local/pgsql/bin/createdb testdb</userinput></screen> |
||||
Then enter: |
||||
<screen><userinput>/usr/local/pgsql/bin/psql testdb</userinput></screen> |
||||
to connect to that database. At the prompt you can enter SQL |
||||
commands and start experimenting. |
||||
</para> |
||||
</step> |
||||
</procedure> |
||||
</sect1> |
||||
|
||||
<sect1 id="install-whatnow"> |
||||
<title>What Now?</title> |
||||
|
||||
<para> |
||||
<itemizedlist> |
||||
<listitem> |
||||
<para> |
||||
The <productname>PostgreSQL</productname> distribution contains a |
||||
comprehensive documentation set, which you should read sometime. |
||||
After installation, the documentation can be accessed by |
||||
pointing your browser to |
||||
<filename>/usr/local/pgsql/doc/html/index.html</filename>, unless you |
||||
changed the installation directories. |
||||
</para> |
||||
|
||||
<para> |
||||
The first few chapters of the main documentation are the Tutorial, |
||||
which should be your first reading if you are completely new to |
||||
<acronym>SQL</acronym> databases. If you are familiar with database |
||||
concepts then you want to proceed with part on server |
||||
administration, which contains information about how to set up |
||||
the database server, database users, and authentication. |
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para> |
||||
Usually, you will want to modify your computer so that it will |
||||
automatically start the database server whenever it boots. Some |
||||
suggestions for this are in the documentation. |
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para> |
||||
Run the regression tests against the installed server (using |
||||
<command>make installcheck</command>). If you didn't run the |
||||
tests before installation, you should definitely do it now. This |
||||
is also explained in the documentation. |
||||
</para> |
||||
</listitem> |
||||
|
||||
<listitem> |
||||
<para> |
||||
By default, <productname>PostgreSQL</productname> is configured to run on |
||||
minimal hardware. This allows it to start up with almost any |
||||
hardware configuration. The default configuration is, however, |
||||
not designed for optimum performance. To achieve optimum |
||||
performance, several server parameters must be adjusted, the two |
||||
most common being <varname>shared_buffers</varname> and |
||||
<varname>work_mem</varname>. |
||||
Other parameters mentioned in the documentation also affect |
||||
performance. |
||||
</para> |
||||
</listitem> |
||||
</itemizedlist> |
||||
</para> |
||||
</sect1> |
||||
|
||||
<xi:include href="postgres.sgml" xpointer="supported-platforms" xmlns:xi="http://www.w3.org/2001/XInclude"/> |
||||
<xi:include href="postgres.sgml" xpointer="installation-platform-notes" xmlns:xi="http://www.w3.org/2001/XInclude"/> |
||||
</article> |
||||
@ -1,97 +0,0 @@ |
||||
<?xml version='1.0'?> |
||||
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" |
||||
version="1.0"> |
||||
|
||||
<!-- |
||||
This is a preprocessing layer to convert the installation instructions into a |
||||
variant without links and references to the main documentation. |
||||
|
||||
- To omit something in the stand-alone INSTALL file, give the element a |
||||
condition="standalone-ignore" attribute. |
||||
|
||||
- If there is no element that exactly covers what you want to change, wrap it |
||||
in a <phrase> element, which otherwise does nothing. |
||||
|
||||
- Otherwise, write a custom rule below. |
||||
--> |
||||
|
||||
<xsl:output |
||||
doctype-public="-//OASIS//DTD DocBook XML V4.5//EN" |
||||
doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/> |
||||
|
||||
<!-- copy everything by default --> |
||||
|
||||
<xsl:template match="@*|node()"> |
||||
<xsl:copy> |
||||
<xsl:apply-templates select="@*|node()" /> |
||||
</xsl:copy> |
||||
</xsl:template> |
||||
|
||||
<!-- particular conversions --> |
||||
|
||||
<xsl:template match="*[@condition='standalone-ignore']"> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="phrase/text()['chapter']"> |
||||
<xsl:text>document</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="phrase[@id='install-ldap-links']"> |
||||
<xsl:text>the documentation about client authentication and libpq</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='collation']"> |
||||
<xsl:text>the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='docguide-toolsets']"> |
||||
<xsl:text>the main documentation's appendix on documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='dynamic-trace']"> |
||||
<xsl:text>the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='install-meson']"> |
||||
<xsl:text>the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='guc-default-toast-compression']"> |
||||
<xsl:text>the configuration parameter default_toast_compression</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='guc-wal-compression']"> |
||||
<xsl:text>the configuration parameter wal_compression</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='locale-providers']"> |
||||
<xsl:text>the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='plpython-python23']"> |
||||
<xsl:text>the </xsl:text><application>PL/Python</application><xsl:text> documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='regress']"> |
||||
<xsl:text>the file </xsl:text> |
||||
<filename>src/test/regress/README</filename> |
||||
<xsl:text> and the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='upgrading']"> |
||||
<xsl:text>the documentation</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='uuid-ossp']"> |
||||
<xsl:text>uuid-ossp</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='xml2']"> |
||||
<xsl:text>xml2</xsl:text> |
||||
</xsl:template> |
||||
|
||||
<xsl:template match="xref[@linkend='sepgsql']"> |
||||
<xsl:text>sepgsql</xsl:text> |
||||
</xsl:template> |
||||
|
||||
</xsl:stylesheet> |
||||
Loading…
Reference in new issue