From 1cbdb435df81b9e4150ea4ed5014b5a00048d8f7 Mon Sep 17 00:00:00 2001 From: Aditya Toshniwal Date: Tue, 25 Feb 2025 17:06:49 +0530 Subject: [PATCH] Update the README.md file based on latest requirements. #8345 --- README.md | 166 +++++++++++++++++++++++------------------------ web/package.json | 2 +- web/yarn.lock | 10 +-- 3 files changed, 88 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 8bbf458b2..2b90b11fa 100644 --- a/README.md +++ b/README.md @@ -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 a web server using a browser, or standalone on a workstation. The runtime/ 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+ -* Yarn +# Building the Web Assets -Change into the runtime directory, and run *yarn install*. This will install the -dependencies required. +pgAdmin is dependent on a number of third party Javascript libraries. These, +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 -*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: +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 -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 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 system Python environment. On Linux and Mac systems, the process is fairly simple - adapt as required for your distribution: @@ -88,36 +106,44 @@ simple - adapt as required for your distribution: configuration may look like: ```python - from config import * + import os + import logging - # Debug mode - DEBUG = True + # Change pgAdmin data directory + DATA_DIR = '/Users/myuser/.pgadmin_dev' - # App mode - SERVER_MODE = True + #Change pgAdmin server and port + DEFAULT_SERVER = '127.0.0.1' + DEFAULT_SERVER_PORT = 5051 - # Enable the test module - MODULE_BLACKLIST.remove('test') + # Switch between server and desktop mode + SERVER_MODE = True - # Log - CONSOLE_LOG_LEVEL = DEBUG - FILE_LOG_LEVEL = DEBUG + #Change pgAdmin config DB path in case external DB is used. + CONFIG_DATABASE_URI="postgresql://postgres:postgres@localhost:5436/pgadmin" - DEFAULT_SERVER = '127.0.0.1' + #Setup SMTP + MAIL_SERVER = 'smtp.gmail.com' + MAIL_PORT = 465 + MAIL_USE_SSL = True + MAIL_USERNAME = 'user@gmail.com' + MAIL_PASSWORD = 'xxxxxxxxxx' - UPGRADE_CHECK_ENABLED = True + # Change log level + CONSOLE_LOG_LEVEL = logging.INFO + FILE_LOG_LEVEL = logging.INFO - # Use a different config DB for each server mode. - if SERVER_MODE == False: - SQLITE_PATH = os.path.join( - DATA_DIR, - 'pgadmin4-desktop.db' - ) - else: - SQLITE_PATH = os.path.join( - DATA_DIR, - 'pgadmin4-server.db' - ) + # Use a different config DB for each server mode. + if SERVER_MODE == False: + SQLITE_PATH = os.path.join( + DATA_DIR, + 'pgadmin4-desktop.db' + ) + else: + SQLITE_PATH = os.path.join( + DATA_DIR, + 'pgadmin4-server.db' + ) ``` This configuration allows easy switching between server and desktop modes @@ -137,9 +163,9 @@ simple - adapt as required for your distribution: (venv) $ python3 $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 - command line interaction with the setup program. +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 +command line interaction with the setup program. 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 @@ -148,49 +174,6 @@ 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. -# 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 *\_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 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* +## 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 Most packages can be built using the Makefile in $PGADMIN4_SRC, provided all diff --git a/web/package.json b/web/package.json index cd6a84f9d..5129b1cd9 100644 --- a/web/package.json +++ b/web/package.json @@ -110,7 +110,7 @@ "date-fns": "^4.1.0", "diff-arrays-of-objects": "^1.1.8", "hotkeys-js": "^3.13.3", - "html-to-image": "^1.11.11", + "html-to-image": "1.11.11", "immutability-helper": "^3.0.0", "insert-if": "^1.1.0", "ip-address": "^10.0.1", diff --git a/web/yarn.lock b/web/yarn.lock index e2de94772..a3bb28dd2 100644 --- a/web/yarn.lock +++ b/web/yarn.lock @@ -8366,10 +8366,10 @@ __metadata: languageName: node linkType: hard -"html-to-image@npm:^1.11.11": - version: 1.11.13 - resolution: "html-to-image@npm:1.11.13" - checksum: 18da77cf6c1e7f821f320dc6941642ee292df136f38c548ecb77aa04718b979df63ba4ea56e53d1939b9dbe8e23ca10c44b55319a885bfe7f5f5023c1b5698fe +"html-to-image@npm:1.11.11": + version: 1.11.11 + resolution: "html-to-image@npm:1.11.11" + checksum: b453beca72a697bf06fae4945e5460d1d9b1751e8569a0d721dda9485df1dde093938cc9bd9172b8df5fc23133a53a4d619777b3d22f7211cd8a67e3197ab4e8 languageName: node linkType: hard @@ -13686,7 +13686,7 @@ __metadata: globals: ^15.13.0 hotkeys-js: ^3.13.3 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 imagemin: ^9.0.0 imagemin-mozjpeg: ^10.0.0