To install and configure PX via the Docker CLI, use the command-line steps in this section.

You must be granted access to the PX-Enterprise container on the Docker hub. Please contact if you need a license key.


If you are using the SaaS version of the PX-Enterprise Lighthouse, then we are hosting your metadata for cloud analytics and a GUI interface to manage your cluster. Please make sure you received the correct token from

If you are NOT using the Portworx hosted SaaS service for management, then note that PX stores configuration metadata in a KVDB (key/value store), such as Etcd or Consul. If you have an existing KVDB, you may use that. If you want to set one up, see the etcd example for PX

Install and configure Docker

PX requires a minimum of Docker version 1.10 to be installed. Follow the Docker install guide to install and start the Docker Service.

If you are runnig a version prior to Docker 1.12, then you must configure Docker to allow shared mounts propogation. Please follow these instructions to enable shared mount propogation. This is needed because PX runs as a container and it will be provisioning storage to other containers.

Specify storage

Portworx pools the storage devices on your server and creates a global capacity for containers. This example uses the two non-root storage devices (/dev/xvdb, /dev/xvdc).

Back up any data on storage devices that will be pooled. Storage devices will be reformatted!

To view the storage devices on your server

Use this command line:

# lsblk

Example output:

Note that devices without the partition are shown under the TYPE column as part.

# lsblk
    NAME                      MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
    xvda                      202:0    0     8G  0 disk
    └─xvda1                   202:1    0     8G  0 part /
    xvdb                      202:16   0    64G  0 disk
    xvdc                      202:32   0    64G  0 disk

Identify the storage devices you will be allocating to PX. PX can run in a heterogeneous environment, so you can mix and match drives of different types. Different servers in the cluster can also have different drive configurations.

Run PX

You can now run PX via the Docker CLI as follows:

# sudo docker run --restart=always --name px -d --net=host     \
                 --privileged=true                             \
                 -v /run/docker/plugins:/run/docker/plugins    \
                 -v /var/lib/osd:/var/lib/osd:shared           \
                 -v /dev:/dev                                  \
                 -v /etc/pwx:/etc/pwx                          \
                 -v /opt/pwx/bin:/export_bin:shared            \
                 -v /var/run/docker.sock:/var/run/docker.sock  \
                 -v /var/cores:/var/cores                      \
                 -v /usr/src:/usr/src                          \
                 -v /lib/modules:/lib/modules                  \
                portworx/px-enterprise -daemon -k etcd:// -c MY_CLUSTER_ID -s /dev/sdb -s /dev/sdc

For Lighthouse users, when you create a cluster in the Lighthouse console, Lighthouse will craft the above command with the correct values for the KVDB and cluster ID.

Important: CoreOS and VMWare Photon users run the command below:

# sudo docker run --restart=always --name px -d --net=host     \
                 --privileged=true                             \
                 -v /run/docker/plugins:/run/docker/plugins    \
                 -v /var/lib/osd:/var/lib/osd:shared           \
                 -v /dev:/dev                                  \
                 -v /etc/pwx:/etc/pwx                          \
                 -v /opt/pwx/bin:/export_bin:shared            \
                 -v /var/run/docker.sock:/var/run/docker.sock  \
                 -v /var/cores:/var/cores                      \
                 -v /lib/modules:/lib/modules                  \
                portworx/px-enterprise -daemon -k etcd:// -c MY_CLUSTER_ID -s /dev/sdb -s /dev/sdc

The following arguments are provided to the PX daemon:

	> Instructs PX to start in daemon mode.  Other modes are for service users only.

	> Points to your key value database, such as an etcd cluster or a consul cluster.

	> Specifies the cluster ID that this PX instance is to join.  You can create any unique name for a cluster ID.

	> Specifies the various drives that PX should use for storing the data.

	> Instructs PX to use any available, unused and unmounted drive.  PX will never use a drive that is mounted.

    > Instructs PX to use any available, unused and unmounted drives or partitions.  PX will never use a drive or partition that is mounted.

	> Optional.  Instructs PX to use an unmounted drive even if it has a filesystem on it.

	> Optional.  Instructs PX to run in zero storage mode.  In this mode, PX can still provide virtual storage to your containers, but the data will come over the network from other PX nodes.

	> Optional.  Specifies the data interface.

	> Optional.  Specifies the management interface.

The following Docker runtime command options are explained:

    > Sets PX to be a privileged container. Required to export block  device and for other functions.

    > Sets communication to be on the host IP address over ports 9001 -9003. Future versions will support separate IP addressing for PX.

    > PX advertises support for asynchronous I/O. It uses shared memory to sync across process restarts

-v /run/docker/plugins
    > Specifies that the volume driver interface is enabled.

-v /dev
    > Specifies which host drives PX can see. Note that PX only uses drives specified in config.json. This volume flage is an alternate to --device=\[\].

-v /etc/pwx/config.json:/etc/pwx/config.json
    > the configuration file location.

-v /var/run/docker.sock
    > Used by Docker to export volume container mappings.

-v /var/lib/osd:/var/lib/osd:shared
    > Location of the exported container mounts. This must be a shared mount.

-v /opt/pwx/bin:/export_bin:shared
    > Exports the PX command line (**pxctl**) tool from the container to the host.

Optional - running with config.json

You can also provide the runtime parameters to PX via a configuration file called config.json. When this is present, you do not need to pass the runtime parameters via the command line. This maybe useful if you are using tools like chef or puppet to provision your host machines.

  1. Download the sample config.json file

  2. Create a directory for the configuration file.

    # sudo mkdir -p /etc/pwx
  3. Move the configuration file to that directory. This directory later gets passed in on the Docker command line.

    # sudo cp -p config.json /etc/pwx
  4. Edit the config.json to include the following:

    • clusterid: This string identifies your cluster and must be unique within your etcd key/value space.
    • kvdb: This is the etcd connection string for your etcd key/value store.
    • devices: These are the storage devices that will be pooled from the prior step.

Example config.json:

      "clusterid": "make this unique in your k/v store",
      "kvdb": [
      "storage": {
        "devices": [

If you are using Compose.IO and the kvdb string ends with [port]/v2/keys, omit the /v2/keys. Before running the container, make sure you have saved off any data on the storage devices specified in the configuration.

You can now start the Portworx container with the following run command:

# sudo docker run --restart=always --name px -d --net=host     \
                 --privileged=true                             \
                 -v /run/docker/plugins:/run/docker/plugins    \
                 -v /var/lib/osd:/var/lib/osd:shared           \
                 -v /dev:/dev                                  \
                 -v /etc/pwx:/etc/pwx                          \
                 -v /opt/pwx/bin:/export_bin:shared            \
                 -v /var/run/docker.sock:/var/run/docker.sock  \
                 -v /var/cores:/var/cores                      \
                 -v /usr/src:/usr/src                          \
                 -v /lib/modules:/lib/modules                  \

At this point, Portworx should be running on your system. To verify, run docker ps.

Authenticated etcd and consul

To use etcd with authentication and a cafile, use this in your config.json:

"kvdb": [
 "username": "root",
 "password": "xxx",
 "cafile": "/etc/pwx/cafile",

To use consul with authentication and a cafile, use this in your config.json:

"kvdb": [
 "username": "root",
 "password": "xxx",
 "cafile": "/etc/pwx/cafile",

Access the pxctl CLI

After Portworx is running, you can create and delete storage volumes through the Docker volume commands or the pxctl command line tool, which is exported to /opt/pwx/bin/pxctl. With pxctl, you can also inspect volumes, the volume relationships with containers, and nodes.

To view all pxctl options, run:

# /opt/pwx/bin/pxctl help

To view global storage capacity

To view the global storage capacity, run:

# sudo /opt/pwx/bin/pxctl status

The following sample output of pxctl status shows that the global capacity for Docker containers is 128 GB.

# /opt/pwx/bin/pxctl status
Status: PX is operational
Node ID: 0a0f1f22-374c-4082-8040-5528686b42be
 	Local Storage Pool: 2 pools
	0	LOW		64 GiB	1.1 GiB	Online	b	us-east-1
	1	LOW		128 GiB	1.1 GiB	Online	b	us-east-1
	Local Storage Devices: 2 devices
	Device	Path		Media Type		Size		Last-Scan
	0:1	/dev/xvdf	STORAGE_MEDIUM_SSD	64 GiB		10 Dec 16 20:07 UTC
	1:1	/dev/xvdi	STORAGE_MEDIUM_SSD	128 GiB		10 Dec 16 20:07 UTC
	total			-			192 GiB
Cluster Summary
	Cluster ID: 55f8a8c6-3883-4797-8c34-0cfe783d9890
	IP		ID					Used	Capacity	Status	0a0f1f22-374c-4082-8040-5528686b42be	2.2 GiB	192 GiB		Online (This node)
Global Storage Pool
	Total Used    	:  2.2 GiB
	Total Capacity	:  192 GiB

For more on using pxctl, see the CLI Reference.

You have now completed setup of Portworx on your first server. To increase capacity and enable high availability, repeat the same steps on each of the remaining two servers. Run pxctl status to view the cluster status. Then, to continue with examples of running stateful applications and databases with Docker and PX, see Application Solutions.

Adding Nodes

To add nodes to increase capacity and enable high availability, simply repeat these steps on other servers. As long as PX is started with the same cluster ID, they will form a cluster.

Application Examples

After you complete this installation, continue with the set up to run stateful containers with Docker volumes:

Edit this page