Single Node Setup

Overview

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

The packagecloud:enterprise license key that was emailed to you.
The packageclod.io API token associated with the user who received the license.
If using S3 for Repository Storage or Backups, you will need an IAM user set up with an AWS access key and secret key.

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

Package Installation

Install the packagecloud:enterprise repository using the instructions emailed to you.
Update the package manager cache.
- Ubuntu/Debian: $ apt-get update
- CentOS/RHEL: $ yum makecache
Install packagecloud from the repository installed in step 1.
- Ubuntu/Debian: $ sudo apt-get install packagecloud
- CentOS/RHEL: $ sudo yum install packagecloud

Configuration

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.

Domain

external_url: The URL and domain name that packagecloud:enterprise will be on. For example: http://packages.example.org. 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 packagecloud.io account the license is registered to.

GPG

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.

S3

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).

Database

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.

Mailer/SMTP

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.

Backups

See our Backups section for more information.

HTTPS

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.

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.
To encrypt a password, you use the packagecloud-ctl encrypt-password command.
- $ packagecloud-ctl encrypt-password password123
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: 'me@local.anctur.space', name: 'julio', password: '$2a$10$yi7irjvgHS8FA0pYUP3Yfuz6XoQlP9wZiGWA2RBM0uzxgFq4r8/Z6'}
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).

Bootstrap

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
Bootstrap the database (if you are not setting up a frontend)
- $ packagecloud-ctl bootstrap-database

Reconfigure

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

Done!

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!