Your first deployment
A repository to a working address, with the mistakes pointed out before you make them.
Thirty minutes, most of it waiting. By the end you will have an application on the internet, a database behind it, and your own domain in front of it.
Do this with something you do not mind breaking.
Before you start
- An organization with some credit on it.
- A repository containing a web application that listens on a port and answers HTTP, with a Dockerfile or a Compose file that builds it.
- The name of a domain, if you want to do the last step. Optional.
1. Connect the repository
Authorise ISOGrid against your code host, and select only the repository you are going to deploy. The connection can be widened later; starting narrow means a mistake here costs nothing.
2. Create the application
Choose the repository, the branch, a region and a size.
The platform now reads the repository and lists what it can build from its Dockerfile or Compose file. If it leaves the choice to you, make it — it does that when a repository genuinely is ambiguous, and guessing would produce an application that fails at three in the morning rather than now. See How the build is detected.
Pick the smallest size that will hold it. Moving up later is a restart, not a rebuild, and starting small means your first bill is not a surprise.
3. Watch the first deployment
The first one is the slowest: nothing is cached yet.
If it fails, read the logs of the failing copy rather than the application in
general. In order of likelihood, it is a missing environment value, the wrong
port, or the application binding to localhost — which inside its own copy
means only this copy, so it is running perfectly and nothing can reach it.
4. Visit the address
You get an encrypted address immediately, with a certificate the platform obtains and renews. Nothing to configure.
Keep this address. It keeps working even when your own domain does not, which makes it the first thing to try when something breaks later.
5. Add a database
Order it separately from the application. It will outlive a hundred deployments.
For a first run, a single arrangement is right: cheapest, and an outage while you are learning is an inconvenience. For anything a customer will touch, read Databases before choosing — the difference between the arrangements is what each one survives.
The connection details stay in the console. Open the database and choose Show connection details whenever you need them again.
6. Connect the two
Set the connection details as environment values on the application. Store the password as a secret, not an ordinary value: a secret is write-only, so it cannot be read back out of a web page later or leave in a screenshot.
Saving an environment value restarts the application, because a program reads its environment once at startup. A secret is different: it reaches the application at its next deployment, so redeploy after setting it.
7. Add a second copy
You have a single copy, which means a gap in service every time you deploy and every time the machine underneath is replaced.
Scale to two. They are placed on different machines, requests are spread, and deployments stop being visible to anyone using the site. This is the single biggest reliability improvement available and it is one setting.
8. Point your own domain at it
Attach the name and create the record the console shows you.
The console does not check the record for you: the domain stays marked Pointed — propagating, so test the name yourself.
The certificate the platform obtains covers the platform address, not your own name. Upload a certificate for your domain on the application's page, and renew it yourself before it expires. See Addresses and domains.
9. Check your backups
Do this before you need it.
Your data is already copied across machines if you chose an arrangement that
does that. That is not a backup. Replication copies a mistaken DELETE to
every copy as faithfully as a good write. Backups protect you from people and
software being wrong; replication protects you from hardware failing. You need
both. A database instance is backed up every day from its creation: open its
Backups view, choose the hour and how long backups are kept, and restore
one once to see that it works.
What to do next
- When things go wrong — worth reading once now, while nothing is broken.
- Command reference — everything here is scriptable.
- Deploying from CI/CD — deploy on every push instead of by hand.