IntenseWebs/pgadmin4
3
0
Fork 0
mirror of https://github.com/pgadmin-org/pgadmin4.git synced 2025-02-25 18:55:31 -06:00
Code Issues Packages Projects Releases Wiki Activity

Convert READMEs to lightly formatted markdown, so they display nicely on Github etc.

Browse Source
This commit is contained in:
Dave Page 2021-02-05 16:18:50 +00:00
parent 5d098fe4b0
commit 530eb3972b
10 changed files with 497 additions and 508 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
README → README.md
View File

@ -1,15 +1,13 @@
pgAdmin 4
=========
# pgAdmin 4
pgAdmin 4 is a rewrite of the popular pgAdmin3 management tool for the
PostgreSQL (http://www.postgresql.org) database.
In the following documentation and examples, "$PGADMIN4_SRC/" is used to denote
In the following documentation and examples, *$PGADMIN4_SRC/* is used to denote
the top-level directory of a copy of the pgAdmin source tree, either from a
tarball or a git checkout.
Architecture
------------
## Architecture
pgAdmin 4 is written as a web application in Python, using jQuery and Bootstrap
for the client side processing and UI. On the server side, Flask is being
@ -20,40 +18,38 @@ a web server using a browser, or standalone on a workstation. The runtime/
subdirectory contains an NWjs based runtime application intended to allow this,
which will execute the Python server and display the UI.
Building the Runtime
--------------------
## Building the Runtime
To build the runtime, the following packages must be installed:
- NodeJS 12+
- Yarn
* NodeJS 12+
* Yarn
Change into the runtime directory, and run "yarn install". This will install the
Change into the runtime directory, and run *yarn install*. This will install the
dependencies required.
In order to use the runtime in a development environment, you'll need to copy
dev_config.json.in file to dev_config.json, and edit the paths to the Python
executable and pgAdmin.py file, otherwise the runtime will use the default
*dev_config.json.in* file to *dev_config.json*, and edit the paths to the Python
executable and *pgAdmin.py* file, otherwise the runtime will use the default
paths it would expect to find in the standard package for your platform.
You can then execute the runtime by running something like:
node_modules/nw/nwjs/nw .
node_modules/nw/nwjs/nw .
or on macOS:
node_modules/nw/nwjs/nwjs.app/Contents/MacOS/nwjs .
node_modules/nw/nwjs/nwjs.app/Contents/MacOS/nwjs .
Create Database Migrations
--------------------------
# Create Database Migrations
In order to make changes to the SQLite DB, navigate to the 'web' directory:
(pgadmin4) $ cd $PGADMIN4_SRC/web
(pgadmin4) $ cd $PGADMIN4_SRC/web
Create a migration file with the following command:
(pgadmin4) $ FLASK_APP=pgAdmin4.py flask db revision
(pgadmin4) $ FLASK_APP=pgAdmin4.py flask db revision
This will create a file in: $PGADMIN4_SRC/web/migrations/versions/ .
Add any changes to the 'upgrade' function.
@ -61,8 +57,7 @@ Increment the SCHEMA_VERSION in $PGADMIN4_SRC/web/pgadmin/model/__init__.py file
There is no need to increment the SETTINGS_SCHEMA_VERSION.
Configuring the Python Environment
----------------------------------
# Configuring the Python Environment
In order to run the Python code, a suitable runtime environment is required.
Python version 3.5 and later are currently supported. It is recommended that a
@ -70,41 +65,41 @@ Python Virtual Environment is setup for this purpose, rather than using the
system Python environment. On Linux and Mac systems, the process is fairly
simple - adapt as required for your distribution:
1) Install the virtualenv packages into the system Python environment
1. Install the virtualenv packages into the system Python environment
$ sudo pip install virtualenv virtualenvwrapper
$ sudo pip install virtualenv virtualenvwrapper
2) Source the virtualenv wrapper tools script. You may want to add this command
2. Source the virtualenv wrapper tools script. You may want to add this command
to your ~/.bash_profile file for future convenience:
$ source /usr/local/bin/virtualenvwrapper.sh
$ source /usr/local/bin/virtualenvwrapper.sh
3) Create a virtual environment:
3. Create a virtual environment:
$ mkvirtualenv pgadmin4
$ mkvirtualenv pgadmin4
To make use of the virtual environment in the future, use the following
command to re-activate it:
$ workon pgadmin4
$ workon pgadmin4
4) Ensure that a PostgreSQL installation's bin/ directory is in the path (so
4. Ensure that a PostgreSQL installation's bin/ directory is in the path (so
pg_config can be found for building psycopg2), and install the required
packages:
(pgadmin4) $ PATH=$PATH:/usr/local/pgsql/bin pip install -r $PGADMIN4_SRC/requirements.txt
(pgadmin4) $ PATH=$PATH:/usr/local/pgsql/bin pip install -r $PGADMIN4_SRC/requirements.txt
If you are planning to run the regression tests, you also need to install
additional requirements from web/regression/requirements.txt:
(pgadmin4) $ pip install -r $PGADMIN4_SRC/web/regression/requirements.txt
(pgadmin4) $ pip install -r $PGADMIN4_SRC/web/regression/requirements.txt
5) Create a local configuration file for pgAdmin. Edit
5. Create a local configuration file for pgAdmin. Edit
$PGADMIN4_SRC/web/config_local.py and add any desired configuration options
(use the config.py file as a reference - any settings duplicated in
config_local.py will override those in config.py). A typical development
configuration may look like:
```python
from config import *
# Debug mode
@ -135,19 +130,19 @@ simple - adapt as required for your distribution:
DATA_DIR,
'pgadmin4-server.db'
)
```
This configuration allows easy switching between server and desktop modes
for testing.
6) The initial setup of the configuration database is interactive in server
mode, and non-interactive in desktop mode. You can run it either by
6. The initial setup of the configuration database is interactive in server
mode, and non-interactive in desktop mode. You can run it either by
running:
(pgadmin4) $ python $PGADMIN4_SRC/web/setup.py
(pgadmin4) $ python $PGADMIN4_SRC/web/setup.py
or by starting pgAdmin 4:
(pgadmin4) $ python $PGADMIN4_SRC/web/pgAdmin4.py
(pgadmin4) $ python $PGADMIN4_SRC/web/pgAdmin4.py
Whilst it is possible to automatically run setup in desktop mode by running
the runtime, that will not work in server mode as the runtime doesn't allow
@ -158,13 +153,12 @@ server or desktop mode, and access it from a web browser using the URL shown in
the terminal once pgAdmin has started up.
Setup of an environment on Windows is somewhat more complicated unfortunately,
please see pkg/win32/README.txt for complete details.
please see *pkg/win32/README.txt* for complete details.
Once a virtual environment has been created and enabled, setup can continue
from step 4 above.
Building the Web Assets
-----------------------
## Building the Web Assets
pgAdmin is dependent on a number of third party Javascript libraries. These,
along with it's own Javascript code, SCSS/CSS code and images must be
@ -180,47 +174,44 @@ download the required packages and build the bundle:
(pgadmin4) $ make install-node
(pgadmin4) $ make bundle
On Windows systems (where "make" is not available, the following commands
On Windows systems (where "make" is not available), the following commands
can be used:
C:\> cd $PGADMIN4_SRC\web
C:\$PGADMIN4_SRC\web> yarn install
C:\$PGADMIN4_SRC\web> yarn run bundle
Creating pgAdmin themes
-----------------------
## Creating pgAdmin themes
To create a pgAdmin theme, you need to create a directory under
web/pgadmin/static/scss/resources.
Copy the sample file _theme.variables.scss.sample to the new directory and
rename it to _theme.variables.scss. Change the desired hexadecimal values of
*web/pgadmin/static/scss/resources*.
Copy the sample file *_theme.variables.scss.sample* to the new directory and
rename it to *_theme.variables.scss*. Change the desired hexadecimal values of
the colors and bundle pgAdmin. You can also add a preview image in the theme
directory with the name as <dir name>_preview.png. It is recommended that the
directory with the name as *\<dir name>_preview.png*. It is recommended that the
preview image should not be larger in size as it may take time to load on slow
networks. Run the yarn run bundle and you're good to go. No other changes are
networks. Run the *yarn run bundle* and you're good to go. No other changes are
required, pgAdmin bundle will read the directory and create other required
entries to make them available in preferences.
The name of the theme is derived from the directory name. Underscores (_) and
hyphens (-) will be replaced with spaces and the result will be camel cased.
Building the documentation
--------------------------
# Building the documentation
In order to build the docs, an additional Python package is required in the
virtual environment. This can be installed with the pip package manager:
$ workon pgadmin4
(pgadmin4) $ pip install Sphinx
The docs can then be built using the Makefile in $PGADMIN4_SRC, e.g.
The docs can then be built using the Makefile in *$PGADMIN4_SRC*, e.g.
(pgadmin4) $ make docs
The output can be found in $PGADMIN4_SRC/docs/en_US/_build/html/index.html
The output can be found in *$PGADMIN4_SRC/docs/en_US/_build/html/index.html*
Building packages
-----------------
# Building packages
Most packages can be built using the Makefile in $PGADMIN4_SRC, provided all
the setup and configuration above has been completed.
@ -229,23 +220,20 @@ To build a source tarball:
(pgadmin4) $ make src
To build a PIP Wheel, activate either a Python 2 or Python 3 virtual
environment as desired, configured with all the required packages, and then
run:
To build a PIP Wheel, activate either a Python 3 virtual environment, configured
with all the required packages, and then run:
(pgadmin4) $ make pip
To build the macOS AppBundle, please see pkg/mac/README.
To build the macOS AppBundle, please see *pkg/mac/README*.
To build the Windows installer, please see pkg/win32/README.txt.
To build the Windows installer, please see *pkg/win32/README.txt*.
Support
-------
## Support
See https://www.pgadmin.org/support/ for support options.
Project info
------------
## Project info
The source code repository can be found here:
@ -261,7 +249,3 @@ If you wish to discuss pgAdmin 4, or contribute to the project, please use the
pgAdmin Hackers mailing list:
pgadmin-hackers@postgresql.org
--
Dave Page
pgAdmin Project Lead

153
pkg/debian/README
View File

@ -1,48 +1,50 @@
# pgAdmin Debian/Ubuntu Builds
This directory contains the build runner script for creating .DEB packages for
Debian and Ubuntu.
Supported platforms
===================
## Supported platforms
Debian 9 & 10
Ubuntu 16.04, 18.04, 19.04 & 19.10
* Debian 9 & 10
* Ubuntu 16.04, 18.04, 19.04 & 19.10
Build configuration
===================
## Build configuration
To build Debian/Ubuntu packages, first run the setup.sh script as root to
install the required pre-requisites, e.g.
# pkg/debian/setup.sh
Building packages
=================
## Building packages
To build a set of packages, from the top-level source directory run:
$ make debian
or
or:
$ pkg/debian/build.sh
Four .deb packages will be created in the dist/ directory:
pgadmin4_<version>_<distro>_<distro_version>_all.deb
A convenience package that depends on all the others.
*pgadmin4_<version>_<distro>_<distro_version>_all.deb*
pgadmin4-server_<version>_<distro>_<distro_version>_<arch>.deb
The core server, e.g. the Python and JS code and the online documentation.
A convenience package that depends on all the others.
pgadmin4-desktop_<version>_<distro>_<distro_version>_<arch>.deb
The desktop runtime. Requires the server package.
*pgadmin4-server_<version>_<distro>_<distro_version>_<arch>.deb*
pgadmin4-web_<version>_<distro>_<distro_version>_<arch>.deb
The server mode setup script for configuring Apache HTTPD. Requires the
server package.
The core server, e.g. the Python and JS code and the online documentation.
Building a repo
===============
*pgadmin4-desktop_<version>_<distro>_<distro_version>_<arch>.deb*
The desktop runtime. Requires the server package.
*pgadmin4-web_<version>_<distro>_<distro_version>_<arch>.deb*
The server mode setup script for configuring Apache HTTPD. Requires the server
package.
## Building a repo
An APT repo can be created by building DEBs for the required platforms, moving
them into the required directory structure, and then running a number of
@ -50,41 +52,41 @@ commands to create the required metadata. The pgAdmin repos use the following
structure (which doesn't entirely follow the normal structure for APT, but
does seem to work well unlike other attempts):
<root>
bionic
dists
pgadmin4
InRelease
main
binary-all
Packages
Packages.gz
pgadmin4_4.21_all.deb
pgadmin4-web_4.21_all.deb
binary-amd64
Packages
Packages.gz
pgadmin4-desktop_4.21_amd64.deb
pgadmin4-server_4.21_amd64.deb
binary-i386
Packages
Packages.gz
Release
Release.gpg
Release.gz
buster
disco
eoan
focal
README
stretch
xenial
<root>
bionic
dists
pgadmin4
InRelease
main
binary-all
Packages
Packages.gz
pgadmin4_4.21_all.deb
pgadmin4-web_4.21_all.deb
binary-amd64
Packages
Packages.gz
pgadmin4-desktop_4.21_amd64.deb
pgadmin4-server_4.21_amd64.deb
binary-i386
Packages
Packages.gz
Release
Release.gpg
Release.gz
buster
disco
eoan
focal
README
stretch
xenial
Note that only the first branches are shown above; other branches (e.g. for
buster, disco etc. follow the structure shown for bionic.
Technically there are actually multiple repos here, one for each OS release.
Note also that the binary-i386 directories do not contain any packages as we're
Note also that the *binary-i386* directories do not contain any packages as we're
not building 32bit packages for Linux. The directories and package indexes are
present though, to prevent warnings being emitted on amd64 machines which are
configured to support 32bit packages as well.
@ -92,58 +94,55 @@ configured to support 32bit packages as well.
In order to sign the repositories you need to import your signing private key
into the gnupg2 keystore, for example:
gpg --import signing_key.priv
gpg --import signing_key.priv
Once the files are in the right structure, we need to run a number of commands
to generate the metadata, and sign the relevant files using GPG (in APT, we
sign the repository indexes rather than the packages themselves.
To create the metadata, first we create a config file for the apt-ftparchive
program in $HOME/aptftp.conf (without the start/end markers):
To create the metadata, first we create a config file for the *apt-ftparchive*
program in *$HOME/aptftp.conf* (without the start/end markers):
----------
APT::FTPArchive::Release {
Origin "pgAdmin Development Team";
Label "pgAdmin 4";
Suite "pgadmin4";
Architectures "amd64 all";
Components "main";
Description "pgAdmin 4 - Development Tools for PostgreSQL";
};
Default {
Packages::Compress ". gzip bzip2";
Sources::Compress ". gzip bzip2";
Contents::Compress ". gzip bzip2";
};
----------
APT::FTPArchive::Release {
Origin "pgAdmin Development Team";
Label "pgAdmin 4";
Suite "pgadmin4";
Architectures "amd64 all";
Components "main";
Description "pgAdmin 4 - Development Tools for PostgreSQL";
};
Default {
Packages::Compress ". gzip bzip2";
Sources::Compress ". gzip bzip2";
Contents::Compress ". gzip bzip2";
};
Next, we create the package indexes. Run the following command for each OS
release to be included (in the example, we're using bionic):
for ARCH in all amd64 i386; do cd <root>/bionic && apt-ftparchive packages -c=$HOME/aptftp.conf dists/pgadmin4/main/binary-${ARCH} > dists/pgadmin4/main/binary-${ARCH}/Packages && gzip -k dists/pgadmin4/main/binary-${ARCH}/Packages; done
for ARCH in all amd64 i386; do cd <root>/bionic && apt-ftparchive packages -c=$HOME/aptftp.conf dists/pgadmin4/main/binary-${ARCH} > dists/pgadmin4/main/binary-${ARCH}/Packages && gzip -k dists/pgadmin4/main/binary-${ARCH}/Packages; done
Now we need to create the release file for each OS release (again, using bionic
in the example:
cd <root>/bionic/dists/pgadmin4 && apt-ftparchive release -c=$HOME/aptftp.conf . > Release && gzip -k Release
cd <root>/bionic/dists/pgadmin4 && apt-ftparchive release -c=$HOME/aptftp.conf . > Release && gzip -k Release
Finally, we can sign the release files. Replace <key name> with the email
address on your signing key:
cd <root>/bionic/dists/pgadmin4 && gpg -u <key name> -bao Release.gpg Release
cd <root>/bionic/dists/pgadmin4 && gpg -u <key name> --clear-sign --output InRelease Release
cd <root>/bionic/dists/pgadmin4 && gpg -u <key name> -bao Release.gpg Release
cd <root>/bionic/dists/pgadmin4 && gpg -u <key name> --clear-sign --output InRelease Release
Note that it is important to run each command in the correct directory (hence
the cd commands) to ensure the relative paths are created correctly in the
indexes.
Repository Configuration
========================
## Repository Configuration
pgAdmin repo configurations live in /etc/apt/sources.list.d/pgadmin4.list. The
pgAdmin repo configurations live in */etc/apt/sources.list.d/pgadmin4.list*. The
file can be created with a command such as:
sudo sh -c 'echo "deb https://server.company.com/apt/$(lsb_release -cs) pgadmin4 main" > /etc/apt/sources.list.d/pgadmin4.list && apt update'
sudo sh -c 'echo "deb https://server.company.com/apt/$(lsb_release -cs) pgadmin4 main" > /etc/apt/sources.list.d/pgadmin4.list && apt update'
Assuming that <root> in the repository structure corresponds to
https://server.company.com/apt/ from the client's perspective.
@ -152,4 +151,4 @@ If you have signed the repository, you'll also need to import the key on the
client. This is done as follows for the pgAdmin signing key; adjust the URL as
needed for your own:
curl http://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo apt-key add
curl http://www.pgadmin.org/static/packages_pgadmin_org.pub | sudo apt-key add

24
pkg/docker/README
View File

@ -1,24 +1,26 @@
# pgAdmin Docker Container Builds
This directory contains the files required to create a docker container running
pgAdmin.
Building
========
## Building
From the top level directory of the pgAdmin source tree, simply run:
docker build .
docker build .
You can also run 'make docker', which will call 'docker build .' but also tag
You can also run *make docker*, which will call *docker build .* but also tag
the image like:
pgadmin4 pgadmin4:latest pgadmin4:4 pgadmin4:4.12
pgadmin4 pgadmin4:latest pgadmin4:4 pgadmin4:4.12
WARNING: The build should be run in a CLEAN source tree. Whilst some potentially
dangerous files such as config_local.py or log files will be explicitly
excluded from the final image, other files will not be.
### WARNING
Running
=======
The build should be run in a CLEAN source tree. Whilst some potentially
dangerous files such as config_local.py or log files will be explicitly
excluded from the final image, other files will not be.
See the documentation at docs/en_US/container_deployment.rst for information on
## Running
See the documentation at *docs/en_US/container_deployment.rst* for information on
running the container.

8
pkg/linux/README
View File

@ -1,3 +1,7 @@
This directory contains package build scripts and assets that are common to various Linux distributions.
# pgAdmin Linux Build Scripts
You should not use them directly!
This directory contains package build scripts and assets that are common to
various Linux distributions.
You should not use them directly, but the functionality provided can be used to
simplify your own build scripts (typically by sourcing *build-functions.sh*).

35
pkg/mac/README
View File

@ -1,35 +0,0 @@
Building pgAdmin4.dmg on macOS
==============================
Required Packages (Either build the sources or get them from macports or
similar):
1. Yarn & NodeJS
2. PostgreSQL installation
- PostgreSQL 12 or above from http://www.postgresql.org/
3. Python 3.5+ (required for building). The build environment should run this
version of python in response to the "python" command.
Building:
1. To bundle a different version of Python from the default of 3.9.0, set the
PGADMIN_PYTHON_VERSION environment variable, e.g:
export PGADMIN_PYTHON_VERSION=3.8.5
2. If a path different from the default of /usr/local/pgsql for the PostgreSQL
installation has been used, set the PGADMIN_POSTGRES_DIR environment variable
appropriately, e.g:
export PGADMIN_POSTGRES_DIR=/opt/local/pgsql
3. If you want to codesign the appbundle, copy codesign.conf.in to
codesign.conf and set the values accordingly.
4. To build, go to pgAdmin4 source root directory and execute "make appbundle".
This will create the python virtual environment and install all the required
python modules mentioned in the requirements file using pip, build the
runtime code and finally create the app bundle and the DMG in ./dist
directory.

41
pkg/mac/README.md Normal file
View File

@ -0,0 +1,41 @@
# pgAdmin macOS Builds
## Required Packages
Either build the sources or get them from macports or similar:
1. Yarn & NodeJS
2. PostgreSQL 12 or above from http://www.postgresql.org/
3. Python 3.6+ (required for building). The build environment should run this
version of python in response to the *python* command.
## Building
1. To bundle a different version of Python from the default of 3.9.0, set the
*PGADMIN_PYTHON_VERSION* environment variable, e.g:
export PGADMIN_PYTHON_VERSION=3.8.5
2. If a path different from the default of /usr/local/pgsql for the PostgreSQL
installation has been used, set the *PGADMIN_POSTGRES_DIR* environment variable
appropriately, e.g:
export PGADMIN_POSTGRES_DIR=/opt/local/pgsql
3. If you want to codesign the appbundle, copy *codesign.conf.in* to
*codesign.conf* and set the values accordingly.
3. If you want to notarize the appbundle, copy *notarization.conf.in* to
*notarization.conf* and set the values accordingly. Note that notarization
will fail if the code isn't signed.
4. To build, go to pgAdmin4 source root directory and execute:
make appbundle
This will create the python virtual environment and install all the required
python modules mentioned in the requirements file using pip, build the
runtime code and finally create the app bundle and the DMG in *./dist*
directory.

142
pkg/redhat/README
View File

@ -1,142 +0,0 @@
This directory contains the build runner script for creating .RPM packages for
Redhat distributions.
Supported platforms
===================
Fedora 30, 31 & 32
RHEL/CentOS 7 & 8
Build configuration
===================
To build RPM packages, first run the setup.sh script as root to install the
required pre-requisites, e.g.
# pkg/redhat/setup.sh
Building packages
=================
To build a set of packages, from the top-level source directory run:
$ make redhat
or
$ pkg/redhat/build.sh
Four .rpm packages will be created in the dist/ directory:
pgadmin4-<version>.<distro>_noarch.rpm
A convenience package that depends on all the others.
pgadmin4-server-<version>.<distro>.<arch>.rpm
The core server, e.g. the Python and JS code and the online documentation.
pgadmin4-desktop-<version>.<distro>.<arch>.rpm
The desktop runtime. Requires the server package.
pgadmin4-web-<version>.<distro>.<arch>.rpm
The server mode setup script for configuring Apache HTTPD. Requires the
server package.
pgadmin4-python3-mod_wsgi-4.7.1-2.el7.<arch>.rpm
The Python 3 build of mod_wsgi for the Apache HTTPD server. Only built
on RHEL/CentOS 7.
Signing Packages
================
It is good practice to sign RPMs to prove their provenance. The build scripts
included in this directory do NOT do that; doing so is done using a Jenkins
task in the pgAdmin buildfarm.
If you want to sign your own RPMs, you'll first need to ensure that the
gnupg2 and rpmsign tools are available on your system.
Then, create a .rpmmacros file in the home directory of the user account that
will be doing the signing. On Fedora 30 and later, and RHEL/CentOS 8 and later,
that should contain the following contents (without the start/end markers).
Replace <your signing key> with the email address in your key:
---------
%_signature gpg
%_gpg_path ~/.gnupg
%_gpg_name <your signing key>
%_gpgbin /usr/bin/gpg2
%__gpg_sign_cmd %{__gpg} gpg --force-v3-sigs --batch --verbose --no-armor --no-secmem-warning -u "%{_gpg_name}" -sbo %{__signature_filename
} --digest-algo sha256 %{__plaintext_filename}
---------
On RHEL/CentOS 7, the .rpmmacros file should look like this:
---------
%_signature gpg
%_gpg_path ~/.gnupg
%_gpg_name Package Manager
%_gpgbin /usr/bin/gpg2
%__gpg_sign_cmd %{__gpg} gpg --force-v3-sigs --batch --verbose --no-armor --passphrase-fd 3 --no-secmem-warning -u "%{_gpg_name}" -sbo %{__
signature_filename} --digest-algo sha256 %{__plaintext_filename}
---------
Note that these configurations are designed for automated signing in a CI/CD
system. You may need to adjust them to handle passphrases on keys in your own
environment.
You also need to import your signing private key into the gnupg2 keystore, for
example:
gpg --import signing_key.priv
Once everything is setup, RPMs can be signed easily; for example:
rpmsign --addsign dist/*.rpm
Building a repo
===============
A Yum repo can be created by building RPMs for the required platforms, moving
them into the required directory structure, and then running the createrepo tool
over that directory. The pgAdmin repos use the following structure:
<root>
redhat/
rhel-7-x86_64/
pgadmin4-4.21-1.el7.noarch.rpm
pgadmin4-desktop-4.21-1.el7.x86_64.rpm
pgadmin4-python3-mod_wsgi-4.7.1-2.el7.x86_64.rpm
pgadmin4-server-4.21-1.el7.x86_64.rpm
pgadmin4-web-4.21-1.el7.noarch.rpm
rhel-8-x86_64/
<...>
fedora/
<...>
pgadmin4-fedora-repo-1-1.noarch.rpm
pgadmin4-redhat-repo-1-1.noarch.rpm
README
Note that only the first branches are shown above; other branches (e.g. for
Fedora and RHEL 8 follow the structure shown for RHEL 7.
Technically there are multiple different repos, one for each platform and
architecture. The metadata can be created for each as follows:
/usr/bin/createrepo <root>/redhat/rhel-7-x86_64
/usr/bin/createrepo <root>/redhat/rhel-8-x86_64
...
Repository RPMs
===============
A script is provided for the creation of repo RPMs. It will create RPMs that
install the required Yum configuration file and the public signing key for
pgAdmin (you may want to replace the contents of PGADMIN_PKG_KEY with your own
public key):
./repo-rpms.sh
Set the PGADMIN_REPO_DIR environment variable to define the repository root
from the client's perspective. Given the example above, you might do:
PGADMIN_REPO_DIR=https://yum.company.com/repos/<root> ./repo-rpms.sh

138
pkg/redhat/README.md Normal file
View File

@ -0,0 +1,138 @@
# pgAdmin Redhat Builds
This directory contains the build runner script for creating .RPM packages for
Redhat distributions.
## Supported platforms
* Fedora 30, 31 & 32
* RHEL/CentOS 7 & 8
## Build configuration
To build RPM packages, first run the setup.sh script as root to install the
required pre-requisites, e.g.
# pkg/redhat/setup.sh
# Building packages
To build a set of packages, from the top-level source directory run:
$ make redhat
or
$ pkg/redhat/build.sh
Four (or five) .rpm packages will be created in the dist/ directory:
*pgadmin4-<version>.<distro>_noarch.rpm*
A convenience package that depends on all the others.
*pgadmin4-server-<version>.<distro>.<arch>.rpm*
The core server, e.g. the Python and JS code and the online documentation.
*pgadmin4-desktop-<version>.<distro>.<arch>.rpm*
The desktop runtime. Requires the server package.
*pgadmin4-web-<version>.<distro>.<arch>.rpm*
The server mode setup script for configuring Apache HTTPD. Requires the server
package.
*pgadmin4-python3-mod_wsgi-4.7.1-2.el7.<arch>.rpm*
The Python 3 build of mod_wsgi for the Apache HTTPD server. Only built on
RHEL/CentOS 7.
## Signing Packages
It is good practice to sign RPMs to prove their provenance. The build scripts
included in this directory do NOT do that; doing so is done using a Jenkins
task in the pgAdmin buildfarm.
If you want to sign your own RPMs, you'll first need to ensure that the
*gnupg2* and *rpmsign* tools are available on your system.
Then, create a *.rpmmacros* file in the home directory of the user account that
will be doing the signing. On Fedora 30 and later, and RHEL/CentOS 8 and later,
that should contain the following contents (without the start/end markers).
Replace <your signing key> with the email address in your key:
%_signature gpg
%_gpg_path ~/.gnupg
%_gpg_name <your signing key>
%_gpgbin /usr/bin/gpg2
%__gpg_sign_cmd %{__gpg} gpg --force-v3-sigs --batch --verbose --no-armor --no-secmem-warning -u "%{_gpg_name}" -sbo %{__signature_filename} --digest-algo sha256 %{__plaintext_filename}
On RHEL/CentOS 7, the .rpmmacros file should look like this:
%_signature gpg
%_gpg_path ~/.gnupg
%_gpg_name Package Manager
%_gpgbin /usr/bin/gpg2
%__gpg_sign_cmd %{__gpg} gpg --force-v3-sigs --batch --verbose --no-armor --passphrase-fd 3 --no-secmem-warning -u "%{_gpg_name}" -sbo %{__
signature_filename} --digest-algo sha256 %{__plaintext_filename}
Note that these configurations are designed for automated signing in a CI/CD
system. You may need to adjust them to handle passphrases on keys in your own
environment.
You also need to import your signing private key into the gnupg2 keystore, for
example:
gpg --import signing_key.priv
Once everything is setup, RPMs can be signed easily; for example:
rpmsign --addsign dist/*.rpm
## Building a repo
A Yum repo can be created by building RPMs for the required platforms, moving
them into the required directory structure, and then running the *createrepo*
tool over that directory. The pgAdmin repos use the following structure:
<root>
redhat/
rhel-7-x86_64/
pgadmin4-4.21-1.el7.noarch.rpm
pgadmin4-desktop-4.21-1.el7.x86_64.rpm
pgadmin4-python3-mod_wsgi-4.7.1-2.el7.x86_64.rpm
pgadmin4-server-4.21-1.el7.x86_64.rpm
pgadmin4-web-4.21-1.el7.noarch.rpm
rhel-8-x86_64/
<...>
fedora/
<...>
pgadmin4-fedora-repo-1-1.noarch.rpm
pgadmin4-redhat-repo-1-1.noarch.rpm
README
Note that only the first branches are shown above; other branches (e.g. for
Fedora and RHEL 8 follow the structure shown for RHEL 7.
Technically there are multiple different repos, one for each platform and
architecture. The metadata can be created for each as follows:
/usr/bin/createrepo <root>/redhat/rhel-7-x86_64
/usr/bin/createrepo <root>/redhat/rhel-8-x86_64
...
## Repository RPMs
A script is provided for the creation of repo RPMs. It will create RPMs that
install the required Yum configuration file and the public signing key for
pgAdmin (you may want to replace the contents of *PGADMIN_PKG_KEY* with your own
public key):
./repo-rpms.sh
Set the *PGADMIN_REPO_DIR* environment variable to define the repository root
from the client's perspective. Given the example above, you might do:
PGADMIN_REPO_DIR=https://yum.company.com/repos/<root> ./repo-rpms.sh

171
pkg/win32/README.md Normal file
View File

@ -0,0 +1,171 @@
# pgAdmin Windows Builds
These notes describe how to setup a Windows development/build environment for
pgAdmin. Only 64 bit builds are supported from v4.30 onwards, however 32 bit
builds may still work with suitable adjustments.
## Installing build requirements
1. Install Visual Studio 2017 Pro from https://my.visualstudio.com/Downloads?q=Visual%20Studio%202017
Choose the Desktop development with C++ option.
2. Install Chocolatey from https://chocolatey.org/install#individual
3. Install various command line tools:
choco install -y bzip2 cmake diffutils dotnet3.5 gzip git innosetup nodejs-lts python strawberryperl wget yarn
4. Upgrade pip (this may give a permissions error that can be ignored):
pip install --upgrade pip
5. Install virtualenv:
pip install virtualenv
## Building dependencies
The following steps should be run from a Visual Studio 2017 64bit command
prompt.
1. Create a directory for the dependencies:
mkdir c:\build64
2. Download the zlib source code, unpack, and build it:
wget https://zlib.net/zlib-1.2.11.tar.gz
tar -zxvf zlib-1.2.11.tar.gz
cd zlib-1.2.11
cmake -DCMAKE_INSTALL_PREFIX=C:/build64/zlib -G "Visual Studio 15 2017 Win64" .
msbuild RUN_TESTS.vcxproj /p:Configuration=Release
msbuild INSTALL.vcxproj /p:Configuration=Release
copy C:\build64\zlib\lib\zlib.lib C:\build64\zlib\lib\zdll.lib
3. Download the OpenSSL source code, unpack and build it:
wget https://www.openssl.org/source/openssl-1.1.1g.tar.gz
tar -zxvf openssl-1.1.1g.tar.gz
cd openssl-1.1.1g
perl Configure VC-WIN64A no-asm --prefix=C:\build64\openssl no-ssl2 no-ssl3 no-comp
nmake
nmake test
nmake install
Note that if you are not working in an administrative account, you may need to
create and give your regular account appropriate permissions to write/modify
files in *C:\Program Files\Common Files\SSL*. This is the default directory used
for the *OPENSSLDIR*, and should not be changed to a directory that un-privileged
users could potentially write to.
4. Download the MIT Kerberos source code, unpack and build it:
In a *32bit* Visual Studio 2017 command prompt:
mkdir C:\build64\krb5
cd krb5-1.18.3\src
set KRB_INSTALL_DIR=C:\build64\krb5
nmake -f Makefile.in prep-windows
Optionally, if you want 32bit binaries as well as 64bit:
nmake NODEBUG=1
nmake install NODEBUG=1
In a *64bit* Visual Studio 2017 command prompt:
cd krb5-1.18.3\src
set PATH=%PATH%;"%WindowsSdkVerBinPath%"\x86
set KRB_INSTALL_DIR=C:\build64\krb5
nmake NODEBUG=1
nmake install NODEBUG=1
5. Download the PostgreSQL source code, unpack and build it:
wget https://ftp.postgresql.org/pub/source/v12.3/postgresql-13.1.tar.bz2
tar -zxvf postgresql-13.1.tar.gz
cd postgresql-13.1\src\tools\msvc
>> config.pl echo # Configuration arguments for vcbuild.
>> config.pl echo use strict;
>> config.pl echo use warnings;
>> config.pl echo.
>> config.pl echo our $config = {
>> config.pl echo asserts =^> 0, # --enable-cassert
>> config.pl echo ldap =^> 1, # --with-ldap
>> config.pl echo extraver =^> undef, # --with-extra-version=^<string^>
>> config.pl echo gss =^> undef, # --with-gssapi=^<path^>
>> config.pl echo icu =^> undef, # --with-icu=^<path^>
>> config.pl echo nls =^> undef, # --enable-nls=^<path^>
>> config.pl echo tap_tests =^> undef, # --enable-tap-tests
>> config.pl echo tcl =^> undef, # --with-tcl=^<path^>
>> config.pl echo perl =^> undef, # --with-perl
>> config.pl echo python =^> undef, # --with-python=^<path^>
>> config.pl echo openssl =^> 'C:\build64\openssl', # --with-openssl=^<path^>
>> config.pl echo uuid =^> undef, # --with-ossp-uuid
>> config.pl echo xml =^> undef, # --with-libxml=^<path^>
>> config.pl echo xslt =^> undef, # --with-libxslt=^<path^>
>> config.pl echo iconv =^> undef, # (not in configure, path to iconv)
>> config.pl echo zlib =^> 'C:\build64\zlib' # --with-zlib=^<path^>
>> config.pl echo };
>> config.pl echo.
>> config.pl echo 1;
>> buildenv.pl echo $ENV{PATH} = "C:\\build64\\openssl\\bin;C:\\build64\\zlib\\bin;$ENV{PATH}";
perl build.pl Release
perl vcregress.pl check
perl install.pl C:\build64\pgsql
copy C:\build64\zlib\bin\zlib.dll C:\build64\pgsql\bin"
copy C:\build64\openssl\bin\libssl-1_1-x64.dll C:\build64\pgsql\bin"
copy C:\build64\openssl\bin\libcrypto-1_1-x64.dll C:\build64\pgsql\bin"
## Setting up a dev environment
This section describes the steps to setup and run pgAdmin for the first time in
a development environment. You do not need to complete this section if you just
want to build an installer.
1. Check out the source code:
git clone https://git.postgresql.org/git/pgadmin4.git
2. Install and build the JS dependencies:
cd pgadmin4\web
yarn install
yarn run bundle
3. Create a virtual env:
cd pgadmin4
python -m venv venv
pip install -r web\regression\requirements.txt
pip install sphinx
You should now be able to run the pgAdmin Python application, or build the
desktop runtime.
## Building an installer
1. Set the required environment variables, either system-wide, or in a Visual
Studio 2017 64bit command prompt. Note that the examples shown below are the
defaults for the build system, so if they match your requirements you don't
need to set them:
SET "PGADMIN_POSTGRES_DIR=C:\Program Files\PostgreSQL\13"
SET "PGADMIN_PYTHON_DIR=C:\Python39"
SET "PGADMIN_KRB5_DIR=C:\jenkins\build64\krb5"
SET "PGADMIN_INNOTOOL_DIR=C:\Program Files (x86)\Inno Setup 6"
SET "PGADMIN_SIGNTOOL_DIR=C:\Program Files (x86)\Windows Kits\10\bin\10.0.17763.0\x64"
SET "PGADMIN_VCREDIST_DIR=C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Redist\MSVC\14.16.27012"
2. Run:
make
If you have a code signing certificate, this will automatically be used if
found in the Windows Certificate Store to sign the installer.
3. Find the completed installer in the dist/ subdirectory of your source tree.

173
pkg/win32/README.txt
View File

@ -1,173 +0,0 @@
These notes describe how to setup a Windows development/build environment for
pgAdmin. They assume a 64bit build is required; adjustments will be required for
a 32bit build.
Installing build requirements
=============================
1) Install Visual Studio 2017 Pro: https://my.visualstudio.com/Downloads?q=Visual%20Studio%202017
Choose the Desktop development with C++ option.
2) Install Chocolatey: https://chocolatey.org/install#individual
3) Install various command line tools:
choco install -y bzip2 cmake diffutils dotnet3.5 gzip git innosetup nodejs-lts python strawberryperl wget yarn
4) Upgrade pip (this may give a permissions error that can be ignored):
pip install --upgrade pip
5) Install virtualenv
pip install virtualenv
Building dependencies
=====================
The following steps should be run from a Visual Studio 2017 64bit command
prompt.
1) Create a directory for the dependencies:
mkdir c:\build64
2) Download the zlib source code, unpack, and build it:
wget https://zlib.net/zlib-1.2.11.tar.gz
tar -zxvf zlib-1.2.11.tar.gz
cd zlib-1.2.11
cmake -DCMAKE_INSTALL_PREFIX=C:/build64/zlib -G "Visual Studio 15 2017 Win64" .
msbuild RUN_TESTS.vcxproj /p:Configuration=Release
msbuild INSTALL.vcxproj /p:Configuration=Release
copy C:\build64\zlib\lib\zlib.lib C:\build64\zlib\lib\zdll.lib
3) Download the OpenSSL source code, unpack and build it:
wget https://www.openssl.org/source/openssl-1.1.1g.tar.gz
tar -zxvf openssl-1.1.1g.tar.gz
cd openssl-1.1.1g
perl Configure VC-WIN64A no-asm --prefix=C:\build64\openssl no-ssl2 no-ssl3 no-comp
nmake
nmake test
nmake install
Note that if you are not working in an administrative account, you may need to
create and give your regular account appropriate permissions to write/modify
files in C:\Program Files\Common Files\SSL. This is the default directory used
for the OPENSSLDIR, and should not be changed to a directory that un-privileged
users could potentially write to.
4) Download the MIT Kerberos source code, unpack and build it:
In a *32bit* Visual Studio 2017 command prompt:
mkdir C:\build64\krb5
cd krb5-1.18.3\src
set KRB_INSTALL_DIR=C:\build64\krb5
nmake -f Makefile.in prep-windows
Optionally, if you want 32bit binaries as well as 64bit:
nmake NODEBUG=1
nmake install NODEBUG=1
In a *64bit* Visual Studio 2017 command prompt:
cd krb5-1.18.3\src
set PATH=%PATH%;"%WindowsSdkVerBinPath%"\x86
set KRB_INSTALL_DIR=C:\build64\krb5
nmake NODEBUG=1
nmake install NODEBUG=1
5) Download the PostgreSQL source code, unpack and build it:
wget https://ftp.postgresql.org/pub/source/v12.3/postgresql-12.3.tar.bz2
tar -zxvf postgresql-12.3.tar.gz
cd postgresql-12.3\src\tools\msvc
>> config.pl echo # Configuration arguments for vcbuild.
>> config.pl echo use strict;
>> config.pl echo use warnings;
>> config.pl echo.
>> config.pl echo our $config = {
>> config.pl echo asserts =^> 0, # --enable-cassert
>> config.pl echo ldap =^> 1, # --with-ldap
>> config.pl echo extraver =^> undef, # --with-extra-version=^<string^>
>> config.pl echo gss =^> undef, # --with-gssapi=^<path^>
>> config.pl echo icu =^> undef, # --with-icu=^<path^>
>> config.pl echo nls =^> undef, # --enable-nls=^<path^>
>> config.pl echo tap_tests =^> undef, # --enable-tap-tests
>> config.pl echo tcl =^> undef, # --with-tcl=^<path^>
>> config.pl echo perl =^> undef, # --with-perl
>> config.pl echo python =^> undef, # --with-python=^<path^>
>> config.pl echo openssl =^> 'C:\build64\openssl', # --with-openssl=^<path^>
>> config.pl echo uuid =^> undef, # --with-ossp-uuid
>> config.pl echo xml =^> undef, # --with-libxml=^<path^>
>> config.pl echo xslt =^> undef, # --with-libxslt=^<path^>
>> config.pl echo iconv =^> undef, # (not in configure, path to iconv)
>> config.pl echo zlib =^> 'C:\build64\zlib' # --with-zlib=^<path^>
>> config.pl echo };
>> config.pl echo.
>> config.pl echo 1;
>> buildenv.pl echo $ENV{PATH} = "C:\\build64\\openssl\\bin;C:\\build64\\zlib\\bin;$ENV{PATH}";
perl build.pl Release
perl vcregress.pl check
perl install.pl C:\build64\pgsql
copy C:\build64\zlib\bin\zlib.dll C:\build64\pgsql\bin"
copy C:\build64\openssl\bin\libssl-1_1-x64.dll C:\build64\pgsql\bin"
copy C:\build64\openssl\bin\libcrypto-1_1-x64.dll C:\build64\pgsql\bin"
Setting up a dev environment
============================
This section describes the steps to setup and run pgAdmin for the first time in
a development environment. You do not need to complete this section if you just
want to build an installer.
1) Check out the source code:
git clone https://git.postgresql.org/git/pgadmin4.git
2) Install and build the JS dependencies
cd pgadmin4\web
yarn install
yarn run bundle
3) Create a virtual env
cd pgadmin4
python -m venv venv
pip install -r web\regression\requirements.txt
pip install sphinx
You should now be able to run the pgAdmin Python application, or build the
desktop runtime.
Building an installer
=====================
1) Set the required environment variables, either system-wide, or in a Visual
Studio 2017 64bit command prompt. Note that the examples shown below are the
defaults for the build system, so if they match your requirements you don't
need to set them:
SET "PGADMIN_POSTGRES_DIR=C:\Program Files\PostgreSQL\13"
SET "PGADMIN_PYTHON_DIR=C:\Python39"
SET "PGADMIN_KRB5_DIR=C:\jenkins\build64\krb5"
SET "PGADMIN_INNOTOOL_DIR=C:\Program Files (x86)\Inno Setup 6"
SET "PGADMIN_SIGNTOOL_DIR=C:\Program Files (x86)\Windows Kits\10\bin\10.0.17763.0\x64"
SET "PGADMIN_VCREDIST_DIR=C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Redist\MSVC\14.16.27012"
2) Run:
make
If you have a code signing certificate, this will automatically be used if
found in the Windows Certificate Store to sign the installer.
3) Find the completed installer in the dist/ subdirectory of your source tree.