Configure environment variables

By default, Upsun exposes some environment variables. Laravel relies heavily on environment variables to configure application services (such as the database or the mailer). Therefore, the default configuration generated by upsun project:init includes the environment variables for all the services connected to your app in the .environment file.

Tip

You can tweak the .environment configuration to fit your needs and add specific project-level variables. You may need a variable to change per environment. If so, use the upsun variable command to add all the needed per-environment variables.

Default environment variables

Upsun automatically exposes environment variables about the app and its infrastructure. Assuming that MySQL, PostgreSQL, and Redis services have been added to your environment, and that the app has been granted access to those services via the following relationships:

.upsun/config.yaml

applications:
  myapp:
    [...]
    relationships:
      mysql: ...
      postgresql: ...
      redis: ...

You can transpose these variables to set up Laravel’s default configuration in a .environment file:

.environment

# Set MySQL database environment variables
export DB_HOST="$MYSQL_HOST"
export DB_PORT="$MYSQL_PORT"
export DB_PATH="$MYSQL_PATH"
export DB_USERNAME="$MYSQL_USERNAME"
export DB_PASSWORD="$MYSQL_PASSWORD"
export DB_SCHEME="$MYSQL_SCHEME"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Or for PostgreSQL
export DB_HOST="$POSTGRESQL_HOST"
export DB_PORT="$POSTGRESQL_PORT"
export DB_PATH="$POSTGRESQL_PATH"
export DB_USERNAME="$POSTGRESQL_USERNAME"
export DB_PASSWORD="$POSTGRESQL_PASSWORD"
export DB_SCHEME="$POSTGRESQL_SCHEME"
export DATABASE_URL="${DB_SCHEME}://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_PATH}"

# Set Laravel-specific environment variables
export DB_CONNECTION="$DB_SCHEME"
export DB_DATABASE="$DB_PATH"

# Set Cache environment variables
export CACHE_HOST="$REDIS_HOST"
export CACHE_PORT="$REDIS_PORT"
export CACHE_SCHEME="$REDIS_SCHEME"
export CACHE_URL="${CACHE_SCHEME}://${CACHE_HOST}:${CACHE_PORT}"

# Set Redis environment variables
export REDIS_URL="$CACHE_URL"

Service environment variables

Each exposed environment variable is prefixed by the relationship name. For example, if you have the following relationships in your configuration:

.upsun/config.yaml

applications:
  myapp:
    relationships:
      database:
        service: "securitydb"
        endpoint: "postgresql"

The environment variables for the database service is prefixed by DATABASE_, which is the upper-cased version of the key defined in the relationship. For example, you could have a DATABASE_URL environment variable.

Environment variables aren’t exposed when the build hook script is running, as services aren’t available during the build process.
To add specific variables available during the build, run upsun variable:create.

Emails

Upsun provides a SMTP service for sending emails. To configure email in Laravel, add the following mapping to your .environment file:

.environment

# Email
export MAIL_MAILER="smtp"
export MAIL_HOST="${PLATFORM_SMTP_HOST}"
export MAIL_PORT="25"

HTTP

If your project has multiple apps, the configuration is exposed via the following environment variables (where SOME_SERVICE is the upper-cased version of the key defined in the relationship):

SOME_SERVICE_URL: The full URL of the service
SOME_SERVICE_IP: The HTTP service IP
SOME_SERVICE_PORT: The HTTP service port
SOME_SERVICE_SCHEME: The HTTP service scheme
SOME_SERVICE_HOST: The HTTP service host

MySQL/MariaDB

The MySQL/MariaDB configuration is exposed via the following environment variables (where DATABASE is the upper-cased version of the key defined in the relationship above):

DATABASE_URL: The database URL (in PHP or Go format depending on your app)
DATABASE_SERVER: The database server
DATABASE_DRIVER: The database driver
DATABASE_VERSION: The database version
DATABASE_HOST: The database host
DATABASE_PORT: The database port
DATABASE_NAME: The database name
DATABASE_DATABASE: Alias for DATABASE_NAME
DATABASE_USERNAME: The database username
DATABASE_PASSWORD: The database password

Tip

The database version and a default charset are included in the database URL. To override them, use the DATABASE_VERSION and DATABASE_CHARSET environment variables respectively.

PostgreSQL

The PostgreSQL configuration is exposed via the following environment variables (where DATABASE is the upper-cased version of the key defined in the relationship):

DATABASE_URL: The database URL (in PHP or Go format depending on your app)
DATABASE_SERVER: The database server
DATABASE_DRIVER: The database driver
DATABASE_VERSION: The database version
DATABASE_HOST: The database host
DATABASE_PORT: The database port
DATABASE_NAME: The database name
DATABASE_DATABASE: Alias for DATABASE_NAME
DATABASE_USERNAME: The database username
DATABASE_PASSWORD: The database password

Tip

The database version and a default charset are included in the database URL. To override them, use the DATABASE_VERSION and DATABASE_CHARSET environment variables respectively.

Redis

The Redis configuration is exposed via the following environment variables (where REDIS is the upper-cased version of the key defined in the relationship):

REDIS_URL: The Redis URL
REDIS_HOST: The Redis host
REDIS_PORT: The Redis port
REDIS_SCHEME: The Redis scheme

You can specify the Redis client in your .environment file:

.environment

export REDIS_CLIENT="phpredis"

Memcached

The Memcached configuration is exposed via the following environment variables (where CACHE is the upper-cased version of the key defined in the relationship):

CACHE_HOST
CACHE_PORT
CACHE_IP

Elasticsearch

The Elasticsearch configuration is exposed via the following environment variables (where ELASTICSEARCH is the upper-cased version of the key defined in the relationship):

ELASTICSEARCH_URL: The full URL of the Elasticsearch service
ELASTICSEARCH_HOST: The Elasticsearch host
ELASTICSEARCH_PORT: The Elasticsearch port
ELASTICSEARCH_SCHEME: The Elasticsearch protocol scheme (http or https)

RabbitMQ

The RabbitMQ configuration is exposed via the following environment variables (where RABBITMQ is the upper-cased version of the key defined in the relationship):

RABBITMQ_URL: The RabbitMQ standardized URL
RABBITMQ_SERVER: The RabbitMQ server
RABBITMQ_HOST: The RabbitMQ host
RABBITMQ_PORT: The RabbitMQ port
RABBITMQ_SCHEME: The RabbitMQ scheme
RABBITMQ_USER: The RabbitMQ username
RABBITMQ_USERNAME: The RabbitMQ username
RABBITMQ_PASSWORD: The RabbitMQ password

MongoDB

The MongoDB configuration is exposed via the following environment variables (where MONGODB is the upper-cased version of the key defined in the relationship):

MONGODB_SERVER
MONGODB_HOST
MONGODB_PORT
MONGODB_SCHEME
MONGODB_NAME
MONGODB_DATABASE
MONGODB_USER
MONGODB_USERNAME
MONGODB_PASSWORD

InfluxDB

The InfluxDB configuration is exposed via the following environment variables (where TIMEDB is the upper-cased version of the key defined in the relationship):

TIMEDB_SCHEME
TIMEDB_HOST
TIMEDB_PORT
TIMEDB_IP

Kafka

The Apache Kafka configuration is exposed via the following environment variables (where KAFKA is the upper-cased version of the key defined in the relationship):

KAFKA_URL
KAFKA_SCHEME
KAFKA_HOST
KAFKA_PORT
KAFKA_IP

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

Configure environment variables

Tip

Default environment variables

Service environment variables

Emails

HTTP

MySQL/MariaDB

Tip

PostgreSQL

Tip

Redis

Memcached

Elasticsearch

RabbitMQ

MongoDB

InfluxDB

Kafka

Tip

​Default environment variables

​Service environment variables

​Emails

​HTTP

​MySQL/MariaDB

Tip

​PostgreSQL

Tip

​Redis

​Memcached

​Elasticsearch

​RabbitMQ

​MongoDB

​InfluxDB

​Kafka

Default environment variables

Service environment variables

Emails

HTTP

MySQL/MariaDB

PostgreSQL

Redis

Memcached

Elasticsearch

RabbitMQ

MongoDB

InfluxDB

Kafka