Backstage in Production with PostgreSQL and Docker

Overview

Running Backstage locally is quick and convenient. By default, it uses an in-memory database and minimal configuration, which makes it ideal for development and experimentation. However, production environments require durability, stability, and consistent deployment practices.

To move Backstage from a development setup to a production-ready system, two foundational improvements are necessary:

1. Replace the in-memory database with PostgreSQL
2. Containerize the application using Docker

We’ll walk through both steps and explain why they are critical for a stable production deployment.

Why the Default Database Is Not Suitable for Production?

Out of the box, Backstage runs with an in-memory database. While this is convenient for testing, it comes with a major limitation:

All data is lost whenever the backend restarts.

That means:

• Catalog entities disappear
• Registered components vanish
• Metadata resets
• Plugin-related data is wiped

For a developer portal that serves as a central source of truth, losing data on restart is unacceptable. Production systems require persistent storage that survives restarts, deployments, and upgrades.

Switching to PostgreSQL for Persistent Storage

PostgreSQL is the recommended database for running Backstage in production. It ensures that all catalog entities, metadata, and plugin data remain intact across restarts.

Provisioning PostgreSQL

You can deploy PostgreSQL in several ways depending on your infrastructure:

Local (Docker-Based) Setup

For testing production-like environments locally:

This runs a PostgreSQL container accessible on port 5432.

Managed Cloud Databases

For real production workloads, managed services are recommended:

• Amazon RDS
• Google Cloud SQL
• Azure Database for PostgreSQL

Managed services offer:

• Automated backups
• High availability
• Failover mechanisms
• Monitoring and scaling support

After provisioning, gather the following details:

• Host
• Port (default 5432)
• Database name
• Username
• Password

These values will be used in the Backstage configuration.

Updating Backstage Configuration

To connect Backstage to PostgreSQL, update the app-config.yaml file:

Field Explanation

• host – PostgreSQL server hostname or IP
• port – Database port (usually 5432)
• user – Database user with proper permissions
• password – Password for the database user
• database – Target database name

Using Environment Variables for Security

Instead of hardcoding credentials inside configuration files, use environment variables:

This approach:

• Keeps sensitive information out of source code
• Simplifies environment separation (dev/stage/prod)
• Integrates well with secret management

Ensure these variables are available in your runtime environment or container.

Starting the Backstage Backend

Once the configuration is complete, start the backend:

yarn workspace backend start

If everything is configured correctly:

• Backstage connects to PostgreSQL
• Required tables are initialized automatically
• Catalog data persists permanently

At this stage, your Backstage instance is no longer ephemeral, a durable relational database backs it.

Containerizing Backstage with Docker

Production systems require consistent deployments across environments. Differences in Node.js versions, operating systems, or dependencies can cause unpredictable behavior.

Docker solves this by packaging:

• Application code
• Dependencies
• Runtime configuration

into a single container image.

Benefits of Containerization

Running Backstage in Docker provides:

• Consistent runtime environments
• Easier CI/CD integration
• Simplified deployment across servers
• Improved portability
• Reduced environment-specific issues

Once containerized, Backstage can be deployed:

• On virtual machines
• Inside container orchestration platforms
• Across staging and production clusters

This ensures predictable and repeatable deployments.

Upgrade Best Practices

Backstage evolves frequently, and upgrading should be handled carefully in production.

Best practices include:

1. Testing upgrades in staging before production rollout
2. Taking PostgreSQL backups before applying updates
3. Reviewing release notes for breaking changes
4. Monitoring database migrations

Because your data resides in PostgreSQL, restarts and upgrades will not erase catalog metadata, but proper planning is essential to avoid disruption.

Conclusion

Moving Backstage to production requires more than simply running the backend server.

Replacing the in-memory database with PostgreSQL ensures that catalog entities and metadata persist across restarts. Containerizing the application with Docker ensures consistent deployments and reduces environment-related issues.

Drop a query if you have any questions regarding Backstage and we will get back to you quickly.