pgadmin-org
/
pgadmin4
mirror of https://github.com/pgadmin-org/pgadmin4.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the README.md file based on latest requirements. #8345

pull/8508/head REL-9_1
Aditya Toshniwal 2025-02-25 17:06:49 +05:30
parent b59495603a
commit 1cbdb435df
3 changed files with 88 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
README.md
View File

@ -15,33 +15,51 @@ and ReactJS, HTML5 with CSS for the client side processing and UI.
Although developed using web technologies, pgAdmin 4 can be deployed either on Although developed using web technologies, pgAdmin 4 can be deployed either on
a web server using a browser, or standalone on a workstation. The runtime/ a web server using a browser, or standalone on a workstation. The runtime/
subdirectory contains an Electron based runtime application intended to allow this, subdirectory contains an Electron based runtime application intended to allow this,
which will execute the Python server and display the UI. which will fork a Python server process and display the UI.
## Building the Runtime ## Prerequisites
1. Install Node.js 20 and above (https://nodejs.org/en/download)
2. yarn (https://yarnpkg.com/getting-started/install)
3. Python 3.8 and above (https://www.python.org/downloads/)
4. PostgreSQL server (https://www.postgresql.org/download)
To build the runtime, the following packages must be installed: Start by enabling Corepack, if it isn't already;
this will add the yarn binary to your PATH:
```bash
corepack enable
```
* NodeJS 16+ # Building the Web Assets
* Yarn
Change into the runtime directory, and run *yarn install*. This will install the pgAdmin is dependent on a number of third party Javascript libraries. These,
dependencies required. along with it's own Javascript code, CSS code and images must be
compiled into a "bundle" which is transferred to the browser for execution
and rendering. This is far more efficient than simply requesting each
asset as it's needed by the client.
In order to use the runtime in a development environment, you'll need to copy To create the bundle, you will need the 'yarn' package management tool to be
*dev_config.json.in* file to *dev_config.json*, and edit the paths to the Python installed. Then, you can run the following commands on a *nix system to
executable and *pgAdmin.py* file, otherwise the runtime will use the default download the required packages and build the bundle:
paths it would expect to find in the standard package for your platform.
You can then execute the runtime by running something like:
```bash ```bash
yarn run start (venv) $ cd $PGADMIN4_SRC
(venv) $ make install-node
(venv) $ make bundle
```
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
``` ```
# Configuring the Python Environment # Configuring the Python Environment
In order to run the Python code, a suitable runtime environment is required. In order to run the Python code, a suitable runtime environment is required.
Python version 3.7 and later are currently supported. It is recommended that a Python version 3.8 and later are currently supported. It is recommended that a
Python Virtual Environment is setup for this purpose, rather than using the Python Virtual Environment is setup for this purpose, rather than using the
system Python environment. On Linux and Mac systems, the process is fairly system Python environment. On Linux and Mac systems, the process is fairly
simple - adapt as required for your distribution: simple - adapt as required for your distribution:
@ -88,24 +106,32 @@ simple - adapt as required for your distribution:
configuration may look like: configuration may look like:
```python ```python
from config import * import os
import logging
# Debug mode # Change pgAdmin data directory
DEBUG = True DATA_DIR = '/Users/myuser/.pgadmin_dev'
# App mode #Change pgAdmin server and port
DEFAULT_SERVER = '127.0.0.1'
DEFAULT_SERVER_PORT = 5051
# Switch between server and desktop mode
SERVER_MODE = True SERVER_MODE = True
# Enable the test module #Change pgAdmin config DB path in case external DB is used.
MODULE_BLACKLIST.remove('test') CONFIG_DATABASE_URI="postgresql://postgres:postgres@localhost:5436/pgadmin"
# Log #Setup SMTP
CONSOLE_LOG_LEVEL = DEBUG MAIL_SERVER = 'smtp.gmail.com'
FILE_LOG_LEVEL = DEBUG MAIL_PORT = 465
MAIL_USE_SSL = True
MAIL_USERNAME = 'user@gmail.com'
MAIL_PASSWORD = 'xxxxxxxxxx'
DEFAULT_SERVER = '127.0.0.1' # Change log level
CONSOLE_LOG_LEVEL = logging.INFO
UPGRADE_CHECK_ENABLED = True FILE_LOG_LEVEL = logging.INFO
# Use a different config DB for each server mode. # Use a different config DB for each server mode.
if SERVER_MODE == False: if SERVER_MODE == False:
@ -137,9 +163,9 @@ simple - adapt as required for your distribution:
(venv) $ python3 $PGADMIN4_SRC/web/pgAdmin4.py (venv) $ python3 $PGADMIN4_SRC/web/pgAdmin4.py
``` ```
Whilst it is possible to automatically run setup in desktop mode by running 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 the runtime, that will not work in server mode as the runtime doesn't allow
command line interaction with the setup program. command line interaction with the setup program.
At this point you will be able to run pgAdmin 4 from the command line in either At this point you will be able to run pgAdmin 4 from the command line in either
server or desktop mode, and access it from a web browser using the URL shown in server or desktop mode, and access it from a web browser using the URL shown in
@ -148,49 +174,6 @@ the terminal once pgAdmin has started up.
Setup of an environment on Windows is somewhat more complicated unfortunately, 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.
# 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
compiled into a "bundle" which is transferred to the browser for execution
and rendering. This is far more efficient than simply requesting each
asset as it's needed by the client.
To create the bundle, you will need the 'yarn' package management tool to be
installed. Then, you can run the following commands on a *nix system to
download the required packages and build the bundle:
```bash
(venv) $ cd $PGADMIN4_SRC
(venv) $ make install-node
(venv) $ make bundle
```
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
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
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
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
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 In order to build the docs, an additional Python package is required in the
@ -210,6 +193,21 @@ The docs can then be built using the Makefile in *$PGADMIN4_SRC*, e.g.
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 the Runtime
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
paths it would expect to find in the standard package for your platform.
You can then execute the runtime by running something like:
```bash
yarn run start
```
# Building packages # Building packages
Most packages can be built using the Makefile in $PGADMIN4_SRC, provided all Most packages can be built using the Makefile in $PGADMIN4_SRC, provided all

2
web/package.json
View File

@ -110,7 +110,7 @@
"date-fns": "^4.1.0", "date-fns": "^4.1.0",
"diff-arrays-of-objects": "^1.1.8", "diff-arrays-of-objects": "^1.1.8",
"hotkeys-js": "^3.13.3", "hotkeys-js": "^3.13.3",
"html-to-image": "^1.11.11", "html-to-image": "1.11.11",
"immutability-helper": "^3.0.0", "immutability-helper": "^3.0.0",
"insert-if": "^1.1.0", "insert-if": "^1.1.0",
"ip-address": "^10.0.1", "ip-address": "^10.0.1",

10
web/yarn.lock
View File

@ -8366,10 +8366,10 @@ __metadata:
languageName: node languageName: node
linkType: hard linkType: hard
"html-to-image@npm:^1.11.11": "html-to-image@npm:1.11.11":
version: 1.11.13 version: 1.11.11
resolution: "html-to-image@npm:1.11.13" resolution: "html-to-image@npm:1.11.11"
checksum: 18da77cf6c1e7f821f320dc6941642ee292df136f38c548ecb77aa04718b979df63ba4ea56e53d1939b9dbe8e23ca10c44b55319a885bfe7f5f5023c1b5698fe checksum: b453beca72a697bf06fae4945e5460d1d9b1751e8569a0d721dda9485df1dde093938cc9bd9172b8df5fc23133a53a4d619777b3d22f7211cd8a67e3197ab4e8
languageName: node languageName: node
linkType: hard linkType: hard
@ -13686,7 +13686,7 @@ __metadata:
globals: ^15.13.0 globals: ^15.13.0
hotkeys-js: ^3.13.3 hotkeys-js: ^3.13.3
html-react-parser: ^5.2.0 html-react-parser: ^5.2.0
html-to-image: ^1.11.11 html-to-image: 1.11.11
image-minimizer-webpack-plugin: ^4.0.2 image-minimizer-webpack-plugin: ^4.0.2
imagemin: ^9.0.0 imagemin: ^9.0.0
imagemin-mozjpeg: ^10.0.0 imagemin-mozjpeg: ^10.0.0