The previous lesson left every decision taken and none of them executed. This is the first time CicloUrbana leaves a development machine and answers at a public internet address. And it does so by the shortest route there is: a platform as a service, where somebody else takes care of the operating system, the server, the TLS certificate, restarting the process if it dies and maintaining PostgreSQL, and we are left with the code and a handful of variables.

Heroku is the PaaS that invented much of the vocabulary the whole industry uses today —the Procfile, buildpacks, config vars, git push as a deployment— and that is why it is still the best place to learn the concepts, even though its free tier disappeared in November 2022. Everything we see here transfers almost literally to Railway, Render, Fly.io, Cloud Run or Azure App Service, and section 3 has the equivalence table so you can follow the lesson on whichever platform you prefer.

1. What a PaaS is and what it does for you
2. Heroku's concepts
3. Heroku today: pricing and equivalent alternatives
4. Prerequisites
5. Preparing CicloUrbana: system.properties and Procfile
6. Creating the application and deploying
7. The database: Heroku Postgres and DATABASE_URL
8. Configuration and secrets with config vars
9. Flyway migrations in the release phase
10. Scaling, dynos and the daily restart
11. Logs and the ephemeral filesystem
12. Custom domain and TLS
13. Alternative: deploying the container image
14. Checking health and monitoring
15. Costs and cleanup
16. The limits of a PaaS
17. Common Mistakes and Tips
18. Exercises

A platform as a service is a hosting model in which you hand over code —or an image— and the platform takes care of absolutely everything underneath. In the table of models in 08-01 it was the "very low operational effort" row.

The bargain is explicit: you give up control in exchange for time. For a project like CicloUrbana in its early phase —one developer, a demo for the council, nobody dedicated to infrastructure— it is an excellent bargain. The point at which it stops being one is covered in section 16.

Two concepts deserve a nuance. The first: a release is slug + configuration, so changing a config var creates a new release and restarts the dynos. It is exactly the model from 08-01: there is one artefact, and the release combines artefact and environment.

The second: a dyno is not a named virtual machine, it is an ephemeral container that can be restarted, moved to another machine or duplicated at any moment. Everything we described in 08-01 about disposable, stateless processes applies here literally, and more strictly than on other platforms.

Important warning: Heroku removed its free tier on 28 November 2022. There are no longer free dynos nor the hobby-dev Postgres plan. To follow this lesson on Heroku you need a card and the spend is real from the first hour: the cheapest plan with a database is around 10-15 dollars a month. There is a Heroku for GitHub Students programme with credit, but it requires an application.

Since the concepts are universal, here is the translation table:

The concepts transfer almost unchanged: on all of them you have to declare the Java version, listen on the port the platform indicates through an environment variable, set the secrets as variables, connect a managed database by URL and write the logs to stdout. If you follow the lesson on Railway or Render, change the CLI commands and the rest fits.

heroku login stores an API token in ~/.netrc. That file is a credential: do not copy it into any repository or image. For automated environments there is heroku authorizations:create, which generates a revocable token with scoped permissions —the correct way to give a pipeline access (08-05)— instead of reusing your personal credentials.

You also need the CicloUrbana repository with mvnw versioned and a clean commit: the deployment is literally a git push.

The Java buildpack (heroku/java) detects the project by the presence of pom.xml and runs ./mvnw -DskipTests clean install. Tests are skipped deliberately: the platform's build is not the place where the module 6 suite runs, that happens in the pipeline (08-05). But the buildpack needs two things you have to declare.

system.properties —at the root of the repository— pins the Java version. Without it, the buildpack uses a default version that may not be 21 and the application will fail with UnsupportedClassVersionError:

Procfile —also at the root, with no extension and with exactly that capital letter— declares the process types:

Every part matters:

• web: is a reserved name: it identifies the process that receives external HTTP traffic. Any other name (worker, release) receives no requests.
• $PORT is mandatory and non-negotiable. Heroku assigns each dyno an arbitrary port at startup time and publishes it in that variable; the router sends traffic there. An application listening on a fixed 8080 receives nothing and after 60 seconds Heroku kills it with the error R10 Boot timeout. This is by far the most common failure of a first deployment.
• MaxRAMPercentage=75 applies here exactly as in the container of 07-04: a Basic dyno has 512 MB and exceeding them produces R14 Memory quota exceeded errors and brutal degradation through swapping.
• target/ciclourbana.jar is the path inside the slug; it matches the finalName in the pom.xml.

As an alternative to -Dserver.port, Spring Boot picks up the SERVER_PORT variable through relaxed binding (02-05), so web: java -jar target/ciclourbana.jar works if you define SERVER_PORT=$PORT. The explicit form in the Procfile is preferable because it keeps the dependency in plain sight.

And one prior check that saves a round trip: application.yml must not pin server.port: 8080 in a way that beats the command line. It does not —the command line has higher precedence (02-04)— but it is worth verifying before blaming the platform.

The command does three things: it reserves the name (globally unique across the whole platform; if it is taken, pick another), it assigns a herokuapp.com domain with TLS already working, and it adds a Git remote called heroku to your local repository. Check it with git remote -v.

That git push is the deployment. What happens next, as read in the build log:

How to read it, line by line:

Mind the branch. Only what you push to the heroku remote gets deployed. If you work on develop, git push heroku develop:main is how you deploy that branch onto Heroku's main one.

It still does not work: the database is missing.

The add-on creates a managed PostgreSQL instance and automatically defines a config var called DATABASE_URL. Here comes the detail that breaks the first deployment of every Spring Boot application on Heroku:

That format is not a valid JDBC URL. It follows the twelve-factor convention —a single value with scheme, credentials and destination— but the PostgreSQL driver expects jdbc:postgresql://host:port/database with the username and password separately. If the application tries to use DATABASE_URL as it stands, startup fails with Driver claims to not accept jdbcUrl.

There are two correct ways to solve it.

Option A (recommended): define the three explicit variables. You read the values from the add-on and translate them into the standard Spring properties:

It is explicit, easy to debug and adds no code. Its drawback is real: Heroku rotates the database credentials during maintenance and upgrades, and when it does it changes DATABASE_URL but not your copied variables. You have to keep an eye on the maintenance notices.

Option B: transform DATABASE_URL at startup. An EnvironmentPostProcessor converts the value before the DataSource is created:

And it is registered in src/main/resources/META-INF/spring.factories:

Details that explain the code: we use an EnvironmentPostProcessor and not a @Bean because it has to run before the autoconfiguration builds the DataSource (02-06); addFirst gives these properties the highest precedence; the early return makes the class harmless outside Heroku, so the same artefact serves everywhere —the principle from 08-01—; and sslmode=require is mandatory, because Heroku Postgres only accepts encrypted connections.

Backups. The add-on takes automatic backups, and they can also be managed by hand:

Remember the principle from 08-01: a backup that has never been restored is not a backup. Try pg:backups:restore on another app, not on the production one.

Look at the connections column and remember the calculation from 08-01: with essential-0 and 20 connections, two dynos with the default pool of 10 exhaust the limit leaving no headroom for migrations or administration. If you are going to scale to two dynos, lower maximum-pool-size to 5.

This is where the profiles from 07-02 fit together with the platform:

Important points:

• SPRING_PROFILES_ACTIVE=prod activates the versioned application-prod.yml (without secrets) from 07-02: Swagger closed, INFO logs, ddl-auto: validate, restricted CORS.
• openssl rand -base64 48 generates the HS256 secret in your terminal and sends it without it ever being written to a file. Never reuse the development secret.
• Every config:set creates a new release and restarts the dynos. Group the changes into a single command so as not to cause several restarts in a row.
• TZ=Europe/Madrid solves the issue from section 7.5 of 08-01: dynos run in UTC.

Security warning. Config vars are encrypted at rest, but they are visible to any collaborator on the app and they appear in heroku config. Apply least privilege within the team, and rotate the JWT secret if somebody leaves the project or if you suspect exposure:

The practical consequence of rotating: every token issued with the previous key stops validating, so citizens will have to authenticate again. It is an acceptable nuisance and the reason why the JWT should be short-lived and there should be a refresh token.

CicloUrbana has seven migrations (V1…V7) and ddl-auto: validate (04-08). There are two ways to apply them, and it is the same dilemma as in section 7.2 of 08-01.

At startup is what the application already does: spring.flyway.enabled: true and Flyway migrates as the context starts. It works with one dyno. With several, they all try to migrate at once and Flyway serialises with a lock: correct, but with two annoying effects —the dynos that wait consume their 60-second startup window, and if the migration fails all the dynos enter a restart loop, leaving the app down even though the previous version worked.

In the release phase is the safe way. You declare a release process type in the Procfile:

How it works: after building the slug and before switching traffic to the new release, Heroku runs the release process on a one-off dyno, with the app's config vars. web-application-type=none makes the application start without Tomcat: the context comes up, Flyway migrates and the process finishes. If it exits with a non-zero code, the release is cancelled and the dynos carry on running the previous version.

The release phase is clearly preferable, and it is the exact equivalent of the ECS one-off task (08-03) and the Kubernetes Job (08-04): factor 12 of the twelve factors, admin processes run as ephemeral processes of the same code.

A practical detail: by disabling Flyway in the web process, ddl-auto: validate still acts as a safety net —if for whatever reason the schema does not match, the application does not start instead of failing query by query.

512 MB is tight for Spring Boot. CicloUrbana with Hibernate, Spring Security and the pool starts at around 250-350 MB of heap plus metaspace. With MaxRAMPercentage=75 it fits, but with no headroom for a spike. If R14 errors appear in the log, the correct answer is Standard-2X, not lowering the percentage to something absurd.

The daily restart (dyno cycling). Heroku restarts every dyno at least once every 24 hours, on top of when a config var changes, when you deploy or when the host machine needs it. It is not a fault: it is the platform imposing factor 9, disposability. Consequences for what we have already built:

• Nothing in memory survives. We already satisfy this: no session, thanks to the JWT (05-04).
• Nothing on disk survives (section 11).
• The scheduled tasks from 07-03 are affected. A task with @Scheduled(fixedDelay = ...) resets its counter on every dyno restart; and with two dynos, both have the scheduler active, so RentalExpirer and OccupancyRecalculator would run twice. ShedLock saves exactly this situation: the shedlock table from migration V7 means only the first dyno to take the lock runs the task and the other skips it. Without ShedLock, scaling to web=2 would mean duplicate reports and recalculating occupancy twice a minute.

A nuance about cron tasks: if a restart happens to coincide with the scheduled time, that execution may be lost. For critical tasks it is worth using an external scheduler —Heroku Scheduler is an add-on— that calls an endpoint or launches a one-off process, instead of depending on the dyno being alive at that exact second.

A dyno's filesystem is ephemeral: each dyno has its own copy of the slug with a writable layer that is destroyed on every restart, and two dynos share nothing. Three rules follow from that:

1. Logs go to stdout. It is factor 11 of 08-01 and what Logback already does by default in CicloUrbana. If the application wrote to logs/ciclourbana.log, that file would disappear on every restart and would be different on each dyno.
2. Files uploaded by users cannot be stored on the dyno. If tomorrow CicloUrbana accepts incident photos, they go into object storage (S3 or equivalent), not onto disk.
3. Heroku's retention is 1,500 lines or one week, whichever comes first. For real production you need an aggregation add-on (Papertrail, Logtail) or forwarding to your own system — the full subject of 09-05.

A formatting detail: Heroku's logs are multiplexed across dynos and processes, and a Java exception stack trace appears as dozens of independent lines. It is a good argument for adopting JSON logs (09-05) and for having the TraceFilter with MDC from 03-06 in place: with the trace identifier on every line, reconstructing one request out of thousands of mixed lines stops being an exercise in patience.

The herokuapp.com domain works with HTTPS from the very first moment. For the council's domain:

At the DNS provider you create a CNAME pointing to the indicated target. Never an A record: Heroku's IP address changes. With the CNAME propagated, Automated Certificate Management requests and renews the certificate through Let's Encrypt automatically. It requires a paid plan (Basic or above).

Two settings in the application close the circle with 08-01 and 05-05:

Heroku's router terminates TLS and speaks HTTP to the dyno, adding X-Forwarded-Proto: https. Without that property, the Location headers of 201 Created responses and the springdoc URLs would come out with http:// and an internal host. And the CORS configuration from 05-05 must allow the final origin https://ciclourbana.ribalta.example, not the test domain.

In 07-04 we built a carefully made image: multi-stage, layered, with a non-root user and JAVA_TOOL_OPTIONS. Heroku can deploy that image instead of building with the buildpack:

It requires a heroku.yml at the root:

If the medium-term plan is to move out to ECS or Kubernetes, deploying the image from the start means the next step is not a leap: the platform changes, the artefact does not. Watch out for $PORT here too: the ENTRYPOINT of the 07-04 image listens on a fixed 8080, so you have to respect the run: web: entry of heroku.yml or parameterise the port.

That /actuator/info with build-info (07-01) answers the question from 08-01: which version is actually running in Ribalta.

A configuration detail specific to Heroku: the separate management port (8081) from 07-01 does not work here, because a dyno can only expose one port, the one in $PORT. On Heroku you have to leave Actuator on the main port behind the security chain we already wrote, with /actuator/health and /actuator/info public and the rest requiring ADMIN:

Monitoring extras: Standard dynos include metrics (memory, response time, throughput) in the dashboard; there are APM add-ons; and heroku ps plus the log show the platform's error codes, which are worth knowing:

Cost warning. Everything in this lesson is billed by prorated hour from the moment it exists, traffic or no traffic.

Mandatory cleanup when you finish the exercise. Destroying the app also removes its add-ons and its backups:

heroku apps:destroy is irreversible and takes the database and its backups with it. If the custom domain was pointing at it, delete the CNAME at the DNS provider too, so as not to leave a record dangling towards a nonexistent target.

A PaaS is the right choice until it stops being one. The signals:

The last point is especially relevant for CicloUrbana: the data of Ribalta's citizens is subject to the GDPR and the council may require hosting in the European Union. Heroku has a European region, but it is a decision you have to take when creating the app (heroku create --region eu), not afterwards.

When any of those signals appears, the natural destination is a managed container model with your own network: exactly what the next lesson does.

Listening on a fixed port. Without $PORT, the dyno receives no traffic and dies with R10 after 60 seconds. It is mistake number one.

A lowercase procfile or one inside a subfolder. Heroku does not find it, the log says Procfile declares types -> (none) and the app does not start. It must be called Procfile, at the root, with no extension.

Using DATABASE_URL as if it were JDBC. The failure is Driver claims to not accept jdbcUrl. Translate it with explicit variables or with the EnvironmentPostProcessor, and do not forget sslmode=require.

Forgetting SPRING_PROFILES_ACTIVE=prod. The app starts with the development configuration exposed to the internet: Swagger open, DEBUG logs and possibly H2. It is exactly the scenario of exercise 3 in 07-02.

Scaling to two dynos without reviewing the pool. With essential-0 (20 connections) and maximum-pool-size: 10, two dynos exhaust the limit and the third process —including the release phase— fails with too many clients.

Scaling to two dynos without ShedLock. Reports come out duplicated and occupancy is recalculated twice. Migration V7 from 07-03 is already there: you only have to verify that the tasks carry @SchedulerLock.

Writing files on the dyno. They disappear on the next restart and are not shared between dynos.

Tip: use a pipeline with pre and prod. Two chained apps and heroku pipelines:promote move the already built slug from one to the other, without rebuilding. It is the principle from 08-01 implemented by the platform.

Tip: heroku releases and heroku rollback are your rollback plan. heroku releases lists the numbered releases and heroku rollback v41 goes back to the previous one in seconds. With the known caveat: the database does not come back, so the schema must remain backwards compatible.

Tip: heroku run bash to inspect. It opens a one-off dyno with the slug and the config vars. Perfect for debugging and also a reminder of why secrets are secrets: whoever can run that sees all of them.

Prepare the CicloUrbana repository for Heroku without deploying anything yet: write system.properties and a Procfile with the web and release processes, decide which config vars are needed and in what order everything runs from git push until the app serves its first request. Explain what would happen if each of the two files were missing.

CicloUrbana is deployed and the log shows, in this order: Java app detected, BUILD SUCCESS, Launching... v3, and then a loop of at=error code=H10 desc="App crashed" with the exception java.lang.IllegalStateException: Cannot load driver class: org.postgresql.Driver ... jdbcUrl is required with driverClassName. The app has the heroku-postgresql:essential-0 add-on created and heroku config shows DATABASE_URL. Diagnose it, fix it in both possible ways and explain which one you would choose for a project planning to migrate to AWS in six months.

CicloUrbana has been on Heroku for a month with web=1, a Basic dyno and essential-0. The council asks for high availability, so it is scaled to web=2. Within 48 hours three problems appear: (a) the nightly occupancy report arrives twice by email, (b) the log shows FATAL: sorry, too many clients already intermittently and (c) during deployments some citizens receive 503. Explain the cause of each one and propose the complete correction, indicating what changes in the application, what in the configuration and what in the platform plan.

Solution 1

system.properties at the root:

Procfile at the root:

Required config vars:

Full sequence: git push heroku main → the buildpack detects the pom.xml → installs JDK 21 as read from system.properties → runs ./mvnw -DskipTests clean install → compresses the slug → reads the Procfile and discovers the release and web types → runs the release process on a one-off dyno, which brings up the context without Tomcat, applies V1…V7 and finishes with code 0 → if the code is 0, it activates release v3 → the web dyno starts, listens on $PORT, validates the schema with ddl-auto: validate and is ready → the router starts sending it traffic.

If system.properties is missing: the buildpack installs its default JDK. If it is older than 21, the build fails compiling Java 21 code, or —worse— it builds and startup dies with UnsupportedClassVersionError.

If the Procfile is missing: the Java buildpack tries to guess the start command from the JAR. It may even work, but without $PORT, so the dyno does not listen where it should and dies with R10 Boot timeout. And there would be no release phase, so the migrations would have to be applied at startup.

Solution 2

Diagnosis. The build succeeded and the app started, so the problem is runtime configuration. The jdbcUrl is required message comes from HikariCP: it did not find spring.datasource.url. The add-on defined DATABASE_URL, but Spring Boot does not recognise it as one of its properties —it expects SPRING_DATASOURCE_URL— and even if it read it, postgres://user:password@host:5432/database is not a JDBC URL: it lacks the jdbc: prefix and carries embedded credentials that the driver does not accept there.

Fix A — explicit variables:

Fix B — EnvironmentPostProcessor: the DatabaseUrlTranslator class from section 7, registered in META-INF/spring.factories, which translates during startup and does nothing outside Heroku.

Which to choose with AWS six months away: A. The reasoning: option B introduces Heroku-specific code inside the artefact, precisely what 08-01 asks you to avoid. It is a piece you would have to maintain, test and, predictably, delete during the migration. Option A solves the problem outside the binary, with the three standard Spring properties, which are exactly the ones that will be used with RDS: migrating will consist of changing their values. The known drawback —Heroku rotates the credentials— is mitigated by documenting it in the runbook and subscribing to the add-on's maintenance notices.

If the horizon were staying on Heroku for years with frequent rotations, B would be defensible; even then, isolated in an integration package and activated by an explicit condition.

Solution 3

(a) The report arrives twice. Both dynos have @EnableScheduling active and each runs its own copy of the task. It is the problem from 07-03 with several instances, now in production. The concrete cause is that the report task does not carry @SchedulerLock, or that the ShedLock configuration is missing. Fix in the application:

lockAtMostFor releases the lock if the dyno dies halfway; lockAtLeastFor prevents a second dyno from running it if the first finished in milliseconds because of a skewed clock. The shedlock table has existed since migration V7, so nothing new is needed in the database. Verification: the log of the dyno that does not run it should show the ShedLock trace stating that it did not acquire the lock.

(b) too many clients already. The essential-0 plan allows 20 connections and maximum-pool-size is 10: two dynos consume exactly those 20, leaving none for the release phase, for heroku pg:psql or for the add-on's monitoring. That is why it is intermittent: it fails precisely when something else asks for a connection. It is the calculation from 08-01:

The fix has two fronts. In the configuration:

With 2 × 6 = 12 there are 8 connections of headroom. And in the plan: move up to essential-2 (40 connections) if performance with 6 is not enough. Remember the principle from 08-01: a large pool is not faster; with 6 connections per dyno and indexed queries, CicloUrbana comfortably serves the traffic of a small city.

(c) 503 during deployments. When deploying, Heroku sends SIGTERM to the old dynos and starts the new ones, but the router may keep sending requests to the dyno that is shutting down for a brief window. If the process stops accepting connections all at once, those requests fail. Fixes:

Graceful shutdown (01-05) lets in-flight requests finish. Heroku allows 30 seconds between SIGTERM and SIGKILL, so 25 s leaves headroom. Complements: scaling to web=3 so that there is always spare capacity during the changeover, and avoiding unnecessary restarts by grouping the config:set calls into a single command instead of chaining several, each with its own release and its own restart.

Summary of the plan. In the application: @SchedulerLock on the tasks and shutdown: graceful with its timeout. In the configuration: maximum-pool-size lowered to 6 and an explicit connection-timeout. In the platform plan: essential-2 if the reduced pool gets tight, and consider web=3. And an underlying conclusion: the three symptoms appeared the day there was more than one instance, which is the moment factors 6, 8 and 9 stop being theory.

CicloUrbana is now on the internet. Anyone with the address can look up Ribalta's stations, authenticate and rent a bike, over HTTPS, with a managed database and automatic backups, and all of it has been achieved without administering a single server. You know what a PaaS does for you and what control you give up in exchange, and you handle its full vocabulary —app, dyno and its types, slug, buildpack, Procfile, config var, release, release phase, pipeline and review app—, with the clear warning that Heroku no longer has a free tier and the table of alternatives where those same concepts appear under other names.

You have prepared the project with system.properties and a Procfile that respects the rule that breaks the most deployments —listening on $PORT—, you have read the build log line by line knowing what to check in each one, and you have solved the classic problem of Heroku's DATABASE_URL, which follows the twelve factors but is not a valid JDBC URL, with both solutions and the criterion for choosing between them. The profiles from 07-02 fitted together with the config vars, the JWT secret was generated outside the repository and you know why and how it is rotated. The Flyway migrations moved to the release phase, which aborts the release if they fail instead of leaving every dyno in a loop: factor 12 in its most concrete form.

You also know what the platform imposes: dynos with tight memory where MaxRAMPercentage stops being a detail, a daily restart that turns disposability into a fact and that requires ShedLock to be properly in place before scaling to two dynos, an ephemeral filesystem that confirms why logs go to stdout, and the calculation of the HikariCP pool against the plan's connection limit. You have added the council's domain with an automatic certificate and forward-headers-strategy so that the URLs come out right behind the proxy, you have checked with /actuator/health and /actuator/info which version is really running, and —very importantly— you have destroyed the app after finishing the exercise, because all of this is billed by the hour.

And you know where the limits are: cost per unit of capacity when scaling, the absence of a private network of your own, reduced control of the environment, the 30-second cut-off, vendor lock-in and the question of region for municipal data subject to the GDPR. When those signals appear, the next step is real infrastructure that is still managed. The next lesson, Deploying to AWS, builds it: an image published in ECR, PostgreSQL in RDS inside private subnets the internet cannot reach, secrets in Secrets Manager, an ECS Fargate service with its task definition, and a load balancer with an ACM certificate that health-checks against /actuator/health/readiness. With the usual warning, and here more seriously: RDS and the load balancer are billed by the hour even if nobody uses the application.