From 743af843ee1ba469a2d6dc2aa6ef049134c7a684 Mon Sep 17 00:00:00 2001 From: Diego Lendoiro Date: Thu, 18 Jan 2018 09:25:37 +0100 Subject: [PATCH] readme update --- README.md | 107 ++++++++++++++++++++++++------------------------------ 1 file changed, 48 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index f5d2bb5..6b08208 100644 --- a/README.md +++ b/README.md @@ -9,27 +9,14 @@ This is a work in progress branch use at your own risk. Passbolt is a free and open source password manager that allows team members to store and share credentials securely. -# Scope of this repository +# Usage -This repository will allow passbolt power users to customize their passbolt image to fit their needs on -specific environments. It is also a community meeting point to exchange feedback, request for new features -track issues and pull requests. - -Users that do not require any special modifications are encouraged to `docker pull` the -[official docker image from the docker hub](https://hub.docker.com/r/passbolt/passbolt/). - -# Build the image - -Inside the repo directory: - -`$ docker build . -t passbolt:local` - -# How to use the local image? +Users are encouraged to use [official docker image from the docker hub](https://hub.docker.com/r/passbolt/passbolt/). ## Start passbolt instance -Passbolt requires mysql to be running. The following example use mysql official docker image -with the default passbolt credentials. +Passbolt requires mysql to be running. The following example use mysql official +docker image with the default passbolt credentials. ```bash $ docker run -e MYSQL_ROOT_PASSWORD= \ @@ -39,26 +26,28 @@ $ docker run -e MYSQL_ROOT_PASSWORD= \ mysql ``` -Then you can start passbolt just by providing the database container ip in the `db_host` environment variable. +Then you can start passbolt just by providing the database container ip in the +`db_host` environment variable. ```bash -$ docker run -e DATASOURCES_DEFAULT_HOST= \ +$ docker run --name passbolt \ + -e DATASOURCES_DEFAULT_HOST= \ -e DATASOURCES_DEFAULT_PASSWORD= \ -e DATASOURCES_DEFAULT_USERNAME= \ -e DATASOURCES_DEFAULT_DATABASE= \ - passbolt:local + -e APP_FULL_BASE_URL=https://mydomain.com \ + passbolt/passbolt:2.0.0-rc1 ``` -Once the process is done, just navigate to the following url in your browser: https://passbolt_container_ip +Once the container is running create your first admin user: -### Note on starting passbolt container on MacOS systems +```bash +$ docker exec passbolt su -m -c "/var/www/passbolt/bin/cake passbolt register_user -u your@email.com -f yourname -l surname -r admin" -s /bin/sh www-data +``` -Due to the [limitations](https://docs.docker.com/docker-for-mac/networking/#known-limitations-use-cases-and-workarounds) -of docker networking under MacOS users should start the container exposing a port on the host: - -`$ docker run -p host_port:443 -e DB_HOST= passbolt:local` - -And access it using https://localhost:host_port +This registration command will return a single use url required to continue the +web browser setup and finish the registration. Your passbolt instance should be +available browsing `https://yourdomain.com` # Configure passbolt @@ -66,44 +55,43 @@ And access it using https://localhost:host_port Passbolt docker image provides several environment variables to configure different aspects: -* APP_FULL_BASE_URL: Defines Passbolt base url (Example https://yourdomain.com) -* DATASOURCES_DEFAULT_HOST: database hostname (defaults to localhost) -* DATASOURCES_DEFAULT_PORT: database port (defaults to 3306) -* DATASOURCES_DEFAULT_USERNAME: database username (defaults to my_app) -* DATASOURCES_DEFAULT_PASSWORD: database password (defaults to secret) -* DATASOURCES_DEFAULT_DATABASE: database name (defaults to my_app) -* EMAIL_DEFAULT_FROM: from email address (defaults to contact@mydomain.local) -* EMAIL_DEFAULT_TRANSPORT: sets transport method (defaults to default) -* EMAIL_TRANSPORT_DEFAULT_HOST: server hostname (defaults to localhost) -* EMAIL_TRANSPORT_DEFAULT_PORT: server port (defaults to 25) -* EMAIL_TRANSPORT_DEFAULT_TIMEOUT: timeout (defaults to 30) -* EMAIL_TRANSPORT_DEFAULT_USERNAME: username for email server auth (defaults to null) -* EMAIL_TRANSPORT_DEFAULT_PASSWORD: password for email server auth (defaults to null) -* EMAIL_TRANSPORT_DEFAULT_CLIENT: client (defaults to null) -* EMAIL_TRANSPORT_DEFAULT_TLS: set tls (defaults to null) -* EMAIL_TRANSPORT_DEFAULT_URL: set url (defaults to null) -* GNUPGHOME: Path to gnupghome directory (defaults to web_user_home_directory/.gnupg ) -* PASSBOLT_KEY_LENGTH: gpg desired key length -* PASSBOLT_SUBKEY_LENGTH: gpg desired subkey length -* PASSBOLT_KEY_NAME: key owner name -* PASSBOLT_KEY_EMAIL: key owner email address -* PASSBOLT_KEY_EXPIRATION: key expiration date +* APP_FULL_BASE_URL: Passbolt base url (Example https://yourdomain.com) +* DATASOURCES_DEFAULT_HOST: database hostname (default: localhost) +* DATASOURCES_DEFAULT_PORT: database port (default: 3306) +* DATASOURCES_DEFAULT_USERNAME: database username (default: my_app) +* DATASOURCES_DEFAULT_PASSWORD: database password (default: secret) +* DATASOURCES_DEFAULT_DATABASE: database name (default: my_app) +* EMAIL_DEFAULT_FROM: from email address (default: contact@mydomain.local) +* EMAIL_DEFAULT_TRANSPORT: sets transport method (default: default) +* EMAIL_TRANSPORT_DEFAULT_HOST: server hostname (default: localhost) +* EMAIL_TRANSPORT_DEFAULT_PORT: server port (default: 25) +* EMAIL_TRANSPORT_DEFAULT_TIMEOUT: timeout (default: 30) +* EMAIL_TRANSPORT_DEFAULT_USERNAME: username for email server auth (default: null) +* EMAIL_TRANSPORT_DEFAULT_PASSWORD: password for email server auth (default: null) +* EMAIL_TRANSPORT_DEFAULT_CLIENT: client (default: null) +* EMAIL_TRANSPORT_DEFAULT_TLS: set tls (default: null) +* EMAIL_TRANSPORT_DEFAULT_URL: set url (default: null) +* GNUPGHOME: Path to gnupghome directory (default: web_user_home_directory/.gnupg ) +* PASSBOLT_KEY_LENGTH: gpg desired key length (default: 2048) +* PASSBOLT_SUBKEY_LENGTH: gpg desired subkey length (default: 2048) +* PASSBOLT_KEY_NAME: key owner name (default: Passbolt default user) +* PASSBOLT_KEY_EMAIL: key owner email address (default: passbolt@yourdomain.com) +* PASSBOLT_KEY_EXPIRATION: key expiration date (default: 0, never expires) * PASSBOLT_GPG_SERVER_KEY_FINGERPRINT: GnuPG fingerprint -* PASSBOLT_GPG_SERVER_KEY_PUBLIC: Path to GnuPG public server key -* PASSBOLT_GPG_SERVER_KEY_PRIVATE: Path to GnuPG private server key -* PASSBOLT_REGISTRATION_PUBLIC: Defines if users can register (defaults to false) -* PASSBOLT_SSL_FORCE: Forces passbolt to redirect to SSL any non-SSL request -* PASSBOLT_SECURITY_SET_HEADERS: Forces passbolt to send CSP Headers (defaults to true) +* PASSBOLT_GPG_SERVER_KEY_PUBLIC: Path to GnuPG public server key (defaults to /var/www/passbolt/config/gpg/serverkey.asc) +* PASSBOLT_GPG_SERVER_KEY_PRIVATE: Path to GnuPG private server key (defaults to /var/www/passbolt/config/gpg/serverkey_private.asc) +* PASSBOLT_REGISTRATION_PUBLIC: Defines if users can register (defaults to false) +* PASSBOLT_SSL_FORCE: Redirects http to https from passbolt (defaults to true) +* PASSBOLT_SECURITY_SET_HEADERS: Send CSP Headers from passbolt (defaults to true) * SECURITY_SALT: A random number user in security hashing methods. -## Advanced configuration +### Configuration files What if you already have a set of gpg keys and custom configuration files for passbolt? It it possible to mount the desired configuration files as volumes. -### Configuration files subject to be persisted: - * /var/www/passbolt/config/app.php +* /var/www/passbolt/config/passbolt.php * /var/www/passbolt/config/gpg/serverkey.asc * /var/www/passbolt/config/gpg/serverkey_private.asc * /var/www/passbolt/app/webroot/img/public/images @@ -117,5 +105,6 @@ It is also possible to mount a ssl certificate on the following paths: # Requirements: -* rng-tools are required on host machine to speed up entropy generation on containers. This way gpg key creation on passbolt container will be faster. +* rng-tools are required on host machine to speed up entropy generation on containers. +This way gpg key creation on passbolt container will be faster. * mysql >= 5.6