Single Node Setup


The installation of packagecloud:enterprise requires no extra software other than a supported operating system running on a machine with at least 2 GB of RAM. Follow the instructions below to get started, it usually takes no more than 5 minutes.

Things you will need

If you have any questions or issues with the installation, please contact support.

Package Installation

  1. Install the packagecloud:enterprise repository using the instructions emailed to you.

  2. Update the package manager cache.

    • Ubuntu/Debian: $ apt-get update
    • CentOS/RHEL: $ yum makecache
  3. Install packagecloud from the repository installed in step 1.

    • Ubuntu/Debian: $ sudo apt-get install packagecloud
    • CentOS/RHEL: $ sudo yum install packagecloud


Use your favorite editor (or config management software) to open /etc/packagecloud/packagecloud.rb, this is where all the configuration for packagecloud:enterprise lives. Don't forget to configure CloudFront in order for packagecloud:enterprise to continue working properly.


  • external_url: The URL and domain name that packagecloud:enterprise will be on. For example: By default, it's set to the hostname of the machine, which may not be what you want.

License Settings

  • packagecloud_rails['enterprise_license_key']: The license key that was emailed to you.

  • packagecloud_rails['api_token']: The API Token of the account the license is registered to.


Be sure to check out the section on GPG if you plan on importing an existing key. If not, the install will generate one for you (recommended).

  • packagecloud_gpg['email']: The email address associated with the public key. Anyone who will import your public key will see this.

Repository Storage

You can choose to store your repository objects (like index files and packages) on S3 (recommended) or Local Filesystem Storage.

Only one Repository Storage backend may be configured at one time and migration between them is not currently supported.


  • packagecloud_rails['aws_access_key']: The access key of the IAM user.

  • packagecloud_rails['aws_secret_key']: The secret key of the IAM user.

  • packagecloud_rails['aws_create_bucket']: Whether we should try to create the given bucket on S3.

  • packagecloud_rails['aws_repo_bucket_name']: The name of the S3 bucket to use, must be globally unique across all of S3, so pick something specific.

  • packagecloud_rails['aws_region']: The AWS region for this bucket, for example: us-west-2

Local Filesystem Storage

  • packagecloud_rails['use_fs']: Whether we should use the Local Filesystem for storage.

  • packagecloud_rails['fs_root']: Where to store the repository objects on the filesystem, the default is /var/opt/packagecloud_storage (recommended).


Skip if not configuring an external database.

You can configure an external database, such as RDS, by setting the following options. The external database should be compatible with at least mysql-5.5

Note: Make sure you have the timezone tables installed into your mysql database. Typically this is done by running the following command: mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

  • packagecloud_rails['database_host']: The host running the database.

  • packagecloud_rails['database_user']: The user to connect as.

  • packagecloud_rails['database_password']: The password to use.

  • packagecloud_rails['database_port']: The port to use, for example 3306.

  • packagecloud_rails['database_name']: Name of the database, will try be created if doesn't exist.


While configuring SMTP isn't strictly necessary, it's a good idea to do so, as password reset emails will not work otherwise.

  • smtp['reply_to']: The reply_to address to use for outgoing mail.
  • smtp['from']: The from address to use for outgoing mail.
  • smtp['address']: Address of the SMTP server.
  • smtp['domain']: The domain for the SMTP server.
  • smtp['enable_starttls_auto']: Whether to automatically start TLS (usually true).

Note: Comment the lines out below to disable SMTP authentication completely.

  • smtp['authentication']: Authentication type to use, for example plain
  • smtp['user_name']: The username to use.
  • smtp['password']: The password to use.


See our Backups section for more information.


See the HTTPS section for more information.

Creating users

Now that we've fully configured our packagecloud:enterprise instance, let's add some users to our seed file.

  1. If Mailer/SMTP wasn't configured above, you'll need to set an encrypted password for the users you add, otherwise a password reset link will be sent to that email.

  2. To encrypt a password, you use the packagecloud-ctl encrypt-password command.

    • $ packagecloud-ctl encrypt-password password123
  3. Edit /etc/packagecloud/users.yml and create an entry using the password from step 2 (remove password field completely if Mailer/SMTP was configured).

    • - {email: '', name: 'julio', password: '$2a$10$yi7irjvgHS8FA0pYUP3Yfuz6XoQlP9wZiGWA2RBM0uzxgFq4r8/Z6'}
  4. Users are automatically loaded as part of reconfigure or bootstrap-install but you can run it manually if adding users in the future.

    • $ packagecloud-ctl load-users

Visit the Users section for more information on user management (like deleting users).


  1. If installing for the first time, you'll need to bootstrap the install. Note: This step might take a few minutes if we are generating a GPG key.

    • $ packagecloud-ctl bootstrap-install
  2. Bootstrap the database (if you are not setting up a frontend)

    • $ packagecloud-ctl bootstrap-database


We can run now run reconfigure, which is also what you run every time you make a change to /etc/packagecloud/packagecloud.rb.

  • $ packagecloud-ctl reconfigure


You should now be able to visit external_url and log in with the account created in /etc/packagecloud/users.yml.

In order to push packages to packagecloud:enterprise you will need to pass some extra flags to the command line client. For example, to push to ubuntu trusty:

  • $ package_cloud push --url http://external_url --config ~/.your-config user/repo/ubuntu/trusty /path/to/file.deb

Happy packaging!

Related Pages