Heroku tutorials, definitions and useful commands

I followed the PHP and Python Heroku tutorials from their official website. While doing so, I saved some notes that might help you in installing the required software for using Heroku locally on your machine. These notes might assist you if you find yourself blocked while following one of the two tutorials because of an error message for example. Let's get started!

NOTE: the following notes make use of PHP 7.2.7, Python 3.6.4, Composer 1.6.5, and Heroku CLI 7.7.7

1. Notes for Tutorial 1: Getting Started on Heroku with PHP
1.1 Prerequisites
1.2 Install Composer (Linux/Unix/macOS)
1.3 Install PHP dependencies locally
2. Notes for Tutorial 2: Getting Started on Heroku with Python
2.1 Prerequisites
2.2 Install Python dependencies locally
2.3 Postgres issue 1: No manual entry for psql [macOS]
2.4 Postgres issue 2: could not connect to Postgres database
3. Important Heroku definitions
4. Heroku commands
4.1 Important Heroku commands
4.2 Add a database
4.3 Deploy an app to Heroku
4.4 Run Django scripts

Notes for Tutorial 1: Getting Started on Heroku with PHP

Prerequisites

These are the prerequisites that you must satisfy before starting the Heroku-PHP tutorial:

PHP: you could use the built-in PHP that comes with your OS (e.g. macOS High Sierra comes with PHP 7.1) or if you want the latest release of PHP, you could install PHP with your favorite package manager (see my tutorial on installing PHP with macOS's Homebrew)
Composer: used for dependency management in PHP projects. See the section on how to install Composer.

Git: the Heroku CLI (that you will install later in their tutorial) makes use of Git.

Open your terminal, and run the following commands to make sure that all the required prerequisites are installed (the commands must all return the number version of the corresponding component):

$ php --version
$ git --version

If Composer was installed globally:

$ composer --version

If Composer was installed locally:

$ php composer.phar --version

Now you are ready to tackle the Heroku-PHP tutorial!

Install Composer (Linux/Unix/macOS)

You can install Composer, either locally as part of your project, or globally as a system-wide executable.

To install Composer locally, do the following:

Open a terminal, and change directory to your PHP project
To run the installer, either:

download the installer to your working directory and check its signature, and run the installer with

$ php installer

or run this script which basically downloads the installer, checks the installer's signature, and runs the installer

NOTE: when running the installer, add the options --install-dir=bin to install Composer in a specific directory and --filename=composer to rename the Composer binary (default name is composer.phar)

Example:

$ php installer --install-dir=bin --filename=composer

Now that Composer is installed (you will see a composer.phar file in your working directory which is the Composer binary), you can run Composer:

$ php composer.phar

To install Composer globally, do the following:

Install Composer locally following all of the above instructions
Move composer.phar to a directory that is in your shell PATH:

$ mv composer.phar /usr/local/bin/composer

You can now run Composer from anywhere in your filesystem, and without directly using the php interpreter:

$ composer

Reference: https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx

Install PHP dependencies locally

NOTE: in this section, we assume that Composer was installed globally, i.e. the command composer is used to run Composer, instead of php composer.phar

The file composer.json in the root directory tells Heroku that it is a PHP app, and it specifies the dependencies that need to be installed with the app.

Two ways to add a PHP dependency:

using Composer:

$ composer require package_name

NOTE:

package_name

Example:

$ composer require monolog/monolog

modifying composer.json:

Example:

{
  "require" : {
    "silex/silex": "^2.0.4",
    "monolog/monolog": "^1.22",
    "twig/twig": "^2.0",
    "symfony/twig-bridge": "^3",
    "alrik11es/cowsayphp": "^1.2"
  },
  "require-dev": {
    "heroku/heroku-buildpack-php": "*"
  }
}

To install the PHP dependencies locally, run the following command:

$ composer update

NOTE 1: see the install command for another command for installing PHP dependencies

NOTE 2: always check the files composer.json and composer.lock in your git repo. However, include the directory vendor (where the third-party dependencies are installed) in your .gitignore file

Notes for Tutorial 2: Getting Started on Heroku with Python

Prerequisites

These are the prerequisites that you must satisfy before starting the Heroku-Python tutorial:

Install Python 3.6
Install Pipenv:

$ pip install --user pipenv

Install Postgres: follow the installation instructions based on your OS
Git: the Heroku CLI (that you will install later in their tutorial) makes use of Git.

Open your terminal, and run the following commands to make sure that all the required prerequisites are installed (the commands must all return the number version of the corresponding component):

$ python --version
$ pipenv --version
$ psql --version
$ git --version

psql should point to the correct psql binary:

$ which psql

For example, on macOS it should point to:

/Applications/Postgres.app/Contents/Versions/latest/bin/psql

Now you are ready to tackle the Heroku-Python tutorial!

Install Python dependencies locally

The file Pipfile (or requirements.txt) in the root directory tells Heroku that it is a Python app, and it specifies the dependencies that need to be installed with the app.

Install the Python dependencies (defined in Pipfile) locally using Pipenv (which creates a virtualenv where the dependencies will be installed):

$ pipenv --three
$ pipenv install

NOTE: --three refers to using Python 3 when creating virtualenv

Then activate the virtualenv:

$ pipenv shell

NOTE: shell spawns a shell within the virutalenv

To run a command inside the virtualenv:

$ pipenv run

To add one specific dependency to your application:

$ pipenv install package_name

Example:

$ pipenv install requests

NOTE: Pipfile is updated with the new requests dependency

Postgres issue 1: No manual entry for psql [macOS]

After configuring your $PATH to include the Postgres command line tools (CLI tools) for macOS, if you type the following to get the official docs:

$ man psql

but unfortunately, you get the following¹:

No manual entry for psql

Then, the problem might be that the path saved in the file /etc/paths.d/postgresapp ends with a slash /, e.g. /Applications/Postgres.app/Contents/Versions/latest/bin/

This trailing slash / causes a problem with the automatic detection of the corresponding man pages. Remove this trailing slash / from the path, and enter again the following to get the official docs:

$ man psql

1.^ see this similar issue on GitHub; the solution is given at the end of the thread by tbussmann

Postgres issue 2: could not connect to Postgres database

If you try to connect remotely to a remote Postgres database (created through Heroku) with:

$ heroku pg:psql

but get this error message:

psql: could not connect to server: Connection refused
 Is the server running on host "xxx-xx-xxx-xxx-xxx.compute-1.amazonaws.com" (xx.xxx.xxx.xxx) and accepting
 TCP/IP connections on port 5432?

Or you try to run commands on a remote Postgres database (created through Heroku) with:

$ heroku run "php -a"

but get this error message:

ECONNREFUSED: connect ECONNREFUSED xx.xx.xxx.xx:5000

Then, an external firewall in your local network might be preventing you from connecting remotely to the Heroku database. For example, you might be connected to a public Wi-Fi in a library. Thus, try to connect to another network such as your cell phone Wi-Fi hotspot or try a VPN service. I tried with the TunnelBear VPN app, and I was able to connect remotely to my Postgres database.

There can also be other possible causes to your Postgres connection issue such as your IP address excluded by the Postgres' access configuration file (pg_hba.conf). A thorough list of common Postgres error messages and their solutions was compiled by Frank Wiles @ revsys.com

As a last note, check that your Postgres database connection requires SSL (sslmode=require) by looking at the PG connection string:

$ heroku pg:credentials:url

Important Heroku definitions

Procfile is a text file in the root directory of your application, that explicitly declares what command should be executed to start your app.

Dyno is a lightweight container that runs the command specified in the Procfile.

A one-off dyno has its own ephemeral filespace, populated with your app and its dependencies - once the command completes (e.g. bash), the dyno is removed.

Config vars are exposed as environment variables to the application (at runtime), and are defined in the .env file (located in the top-level directory of your project). For example, they can store encryption keys or external resource addresses.

Add-ons are third-party services that provide additional services for your application, such as Papertrail for log management, or data stores like Redis and MySQL.

Heroku commands

Important Heroku commands

To know more about a particular Heroku CLI command:

$ heroku -h [COMMAND]

Example:

$ heroku -h create

To login:

$ heroku login

To create an app:

$ heroku create [APP_NAME]

NOTE 1: a git remote (called heroku) is also created
NOTE 2: if no app name is specified, then a random name is assigned

To view logs:

$ heroku logs --tail

NOTE: to stop the log streaming, press Ctrl+C

Check number of dynos that are running:

$ heroku ps

Scale an app, i.e.change the number of dynos that are running:

$ heroku ps:scale web=1

NOTE: here we scale the app to one web dyno

To access the app in a web browser:

$ heroku open [PATH]

Example: open https://myapp.herokuapp.com/foo

$ heroku open -a myapp /foo

NOTE: if the app was already deployed with heroku create, no need to add the option -a

To run a Python app locally (e.g. start up a web server):

$ heroku local [PROCESSNAME]

Example:

$ heroku local web

NOTE 1: heroku local examines the Procfile to know what to run
NOTE 2: you must first install locally the dependencies with $ pipenv install
NOTE 3: open http://localhost:5000 with your web browser

To stop the app from running locally:

Ctrl+C

To run a command using one-off dynos, e.g. scripts and apps that are part of your application:

$ heroku run

Example: start a console, i.e. a Python shell (launch a REPL process attached to your local terminal for experimenting in your app’s environment)

$ heroku run python manage.py shell

Example: start a PHP console, type quit to close the PHP console

$ heroku run "php -a"

Example: start a bash shell, type exit to exit the shell (the dyno is terminated also)

$ heroku run bash

To set a config var:

$ heroku config:set

Example: set the cofig var TIMES

$ heroku  config:set TIMES=2

To view the config vars that are set:

$ heroku config

Add a database

To list the add-ons (e.g. database) installed for your application:

$ heroku addons

To add a Postgres database:

$ heroku addons:create heroku-postgresql:hobby-dev

NOTE 1: a DATABASE_URL config var is added to the environment which you can read with $ heroku config

NOTE 2: installation notes for adding other databases

To know more about the database used by your application (e.g. plan, status, data size):

$ heroku pg

To access the database, append /db to the app's URL, e.g. https://wonderful-app-287.herokuapp.com/db

Example: connect to the remote Postgres database and see all the rows:

$ heroku pg:psql

demo-app::DATABASE=> select * from hello_greeting;

NOTE 1: Postgres needs to be installed locally for this command to work

NOTE 2: to know more about Heroku PostgreSQL

Deploy an app to Heroku

These are steps to deploy an app to Heroku:

Create the app (if you have not done so yet):

$ heroku create

Add the modified files to the local git repository:

$ git add .

Commit the changes to the repository:

$ git commit -m "Demo"

Deploy the app to Heroku:

$ git push heroku master

Check that everything is working by opening the website:

$ heroku open

Run Django scripts

To run the Django scripts, we use the command:

$ heroku run

Example: create tables:

$ heroku run python manage.py migrate

Search This Blog

Programming and technology blog