Elephant Shed is a web-based PostgreSQL management front-end that bundles several utilities and applications for use with PostgreSQL. It currently manages single-node Debian/Ubuntu PostgreSQL servers and appliances.
The main components are:
- PostgreSQL - https://www.postgresql.org/
- pgAdmin4 - https://www.pgadmin.org/
- postgresql-common - https://anonscm.debian.org/cgit/pkg-postgresql/postgresql-common.git
- pgBadger - http://dalibo.github.io/pgbadger/
- pgBackRest - http://www.pgbackrest.org/
- Grafana - https://grafana.com/
- Prometheus - https://prometheus.io/
- Cockpit - http://cockpit-project.org/
- Shell In A Box - https://github.com/shellinabox/shellinabox
In addition several other tools are included for configuration management and setup.
The number of components bundled and tasks handled add some overhead compared to running just the database server. It is therefore only recommended for adequately sized systems.
This document describes the current version.
Updated versions of this document will be shipped with the elephant-shed packages and can be found in
/usr/share/doc/elephant-shed*) and in the web portal under https://your-server/doc/README.html.
Elephant Shed consists of the following Debian packages and their dependencies:
elephant-shed: Metapackage that includes the following packages.
elephant-shed-prometheus: Configuration files and helper scripts for Prometheus and its exporters.
elephant-shed-cockpit: Configuration files for cockpit and cockpit-ws.
elephant-shed-grafana: Preconfigured Prometheus datasource and dashboard that includes various system and PostgreSQL metrics.
elephant-shed-pgadmin4: Configuration files for pgAdmin4.
elephant-shed-pgbackrest: Systemd service files and generators, helper scripts and preset configuration.
elephant-shed-pgbadger: Systemd service files, generators and helper scripts.
elephant-shed-portal: Elephant Shed web portal including Apache configuration.
elephant-shed-postgresql: Additional preset configuration files for PostgreSQL.
elephant-shed-shellinabox: Shell In A Box configuration files.
elephant-shed-tmate: Preconfigured tmate installation for easier support.
Prebuilt packages are available from https://packages.credativ.com/public/postgresql/.
# Install tools sudo apt-get install curl ca-certificates apt-transport-https # Use official PostgreSQL repo, apt.postgresql.org echo "deb http://apt.postgresql.org/pub/repos/apt/ stretch-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgdg.list curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - # Use credativ repo, packages.credativ.com echo "deb https://packages.credativ.com/public/postgresql/ stretch-stable main" | sudo tee -a /etc/apt/sources.list.d/elephant-shed.list curl https://packages.credativ.com/public/postgresql/aptly.key | sudo apt-key add - # Install elephant-shed sudo apt-get update sudo apt-get install elephant-shed # Choose desired PostgreSQL versions to install sudo apt-get install postgresql-10 # Every user in the group "elephant-shed" is allowed to login at the portal # Add all needed users to this group sudo adduser <USERNAME> elephant-shed
The repository also contains packages that the
elephant-shed packages depend
on. This includes packages for Grafana, Cockpit and various python libraries.
Installation from source
The source code is available on GitHub: https://github.com/credativ/elephant-shed
Build Debian Packages
All Elephant Shed Debian packages can be built using the command
To build the documentation in HTML as well as the PDF format type
Create Testsystem with Vagrant
make vagrant command builds all components, creates a new virtual machine using Vagrant and deploys the software using Ansible.
This can also be used to redeploy a already running machine.
The Vagrant configuration is located in
Deploy on remote machine
To deploy the software on any machine, enter the connection information in the inventory
The deployment can than be started with the following command
Log into your web browser and go to the server's IP address (e.g. https://your-server/). The default setup will redirect HTTP requests to HTTPS.
The Elephant Shed portal provides information about running PostgreSQL instances and their status. Moreover you get access to all other installed components.
The server will ask you for your user credentials. Depending on the deployment process the required user will differ. On a test installation (e.g. using Vagrant) the initial user is admin with password admin. See also: Users. All bundled components except for pgAdmin4 have been configured to use PAM authentication.
pgAdmin4 doesn't support PAM authentication yet. It has its own user management system which is decoupled from all system users. You should have been asked about the initial user within the installation setup. If you deployed a Vagrant VM the initial user is [email protected] and admin as password.
On a new installation you will find one cluster running the current PostgreSQL major version with the name
The configuration for clusters can be found in
To use PostgreSQL from external application servers only a few steps are needed.
Open a shell connection to the server using SSH or shellinabox https://your-server/shellinabox.
Switch to user
postgresand launch psql:
sudo -u postgres psql
Create a database and corresponding application user, options:
psql: CREATE ROLE appuser1 WITH LOGIN PASSWORD 'testpass';
psql: CREATE DATABASE appdb1 OWNER appuser1;
Allow external access for your application servers, your network or everyone. Configuration file:
(optional) Make desired configuration changes and tuning.
Reload the configuration, options:
- Portal: Click on the button
Servicenext to the cluster and choose "Reload" from the dropdown menu
- Portal: Click on the button
(optional) Configure a superuser to be able to use pgAdmin4 https://your-server/pgadmin4 or other management tools
- Create password for user postgres:
- Create personalized superusers:
CREATE USER "sosna" SUPERUSER;,
- Create password for user postgres:
The Elephant Shed is based on
postgresql-common, the default PostgreSQL
management system for Debian based installations. Tasks like creating, dropping
or renaming a PostgreSQL instance ("cluster" in PostgreSQL terms) should be
postgresql-common's command line utilities
Beside the postgresql-common default configuration the
elephant-shed-postgresql package adds additional parameters for the cluster
creation process. Some of these parameters are required by the
Elephant Shed components. E.g. pgBadger requires some special
log_line_prefix. You can find this configuration under
careful when changing any of these values.
To create a new cluster issue the command
pg_createcluster <version> <name>.
Installed clusters and their status can be listed via
[email protected]:~$ pg_lsclusters Ver Cluster Port Status Owner Data directory Log file 9.6 main 5432 online postgres /9.6/main /log/9.6-main.log 9.6 standby1 5433 online,recovery postgres /9.6/standby1 /log/9.6-standby1.log 9.6 standby2 5434 online,recovery postgres /9.6/standby2 /log/9.6-standby2.log 9.6 test 5435 online postgres /9.6/test /log/9.6-test.log
To delete a cluster use `pg_dropcluster