Tutorial
A Deploy to Brewless button in your Laravel README
Put a one-click deploy button in a public Laravel repository, so readers run your demo or starter kit in their own Scaleway project.
In this post
If you maintain a Laravel starter kit, a demo app or a package with an example project, you know the gap between "here is the repository" and "I got it running". Clone, copy the .env, find a database, generate a key, run the migrations, and somewhere in there most readers give up.
A deploy button closes that gap. Put one line in your README, and a reader gets your app running on a live address, in infrastructure they own, without opening a terminal.
What does a Deploy to Brewless button do?
It takes a reader from your README to a working copy of your app in their own Scaleway project, in one click. They pick a name, Brewless sets up the application and its production environment the way your brewless.yml describes, and the first release starts.
What it does not do is put the app on your account, or on a shared sandbox that expires. The containers, the database and the bucket are created in the reader's own Scaleway project and billed to them by Scaleway. It is their app from the first second.
Add it to your README
One line of markdown, with your repository after repository=:
[](https://brewless.eu/deploy?repository=github.com/owner/name)
For the other hosts, write codeberg.org/owner/name or gitlab.com/group/name instead. That is the whole integration: no app to install on your repository, no webhook, nothing to configure on the Brewless side.
The link lands on a page on brewless.eu that asks which console the visitor uses, such as acme.brewless.eu, and sends them on to it. Brewless.eu itself does not know who they are, which is why it has to ask; the deploy happens in their own organisation, at /deploy in their console.
Note
The button reads public repositories only, through the code host's public API and without a key. A host that limits callers without a key may ask the reader to try again after a while.
What Brewless reads from your repository
Less than you might expect. Two files at one commit, and nothing else:
| What | Why |
|---|---|
composer.json |
To check the project requires laravel/framework |
brewless.yml |
To shape the environment, when the file is there |
That is the lot. The code itself never passes through Brewless: when the release starts, the build job running inside the reader's own Scaleway project downloads the archive of that commit straight from GitHub, Codeberg or GitLab. The same route a brewless deploy from a laptop takes, minus the laptop.
Ship a brewless.yml, and it is used
If your repository has a brewless.yml, the button deploys its production environment. If the file has no production, it takes the file's default-environment, and failing that its first environment.
Four things in your file are deliberately dropped, because they are yours and not the reader's:
| Left out | Why |
|---|---|
organisation and application |
Replaced by the reader's organisation and the name they type |
domains |
Your domains. The reader adds their own later |
kind and region |
The environment is a production environment in the default region |
Your php, build and release keys do carry over, so a project that needs a particular PHP version or an extra build step still gets one.
Without a brewless.yml, the button falls back to a plain default for a Laravel app: a database named after the repository, and the edge cache on.
environments:
production:
database: name-of-the-repository
edge:
cache: 1h
That default is enough for a demo, but a file of your own is better. It is the one place where you say what your app actually needs, and a reader who later deploys from a fork gets the same thing.
Warning
A file that asks for
servicesis refused. A service is pushed from a machine withbrewless service:push, and the button has no machine. Such a repository has to be deployed with the command line.
What the reader gets
After the click and a name, four things happen in order:
- Brewless reads the repository at the newest commit of its default branch.
- It creates the application, with a Scaleway project of its own when the reader's key is allowed to make projects.
- The production environment is set up as
brewless deploywould have set it up from the file. - The first release starts, and the deployments page of the environment follows it.
The environment gets a test address from Brewless with that deploy, so there is a working URL without anyone owning a domain. Every page on it tells search engines to stay away with X-Robots-Tag: noindex, nofollow, and its robots.txt disallows everything unless your application has a public/robots.txt of its own, so a hundred copies of your demo do not turn up in search results next to the real thing.
The application counts towards the applications of the reader's plan like any other, and deploying takes the right to manage applications as well as a connected Scaleway project.
After the first release
The button makes one release and then steps out of the way. The application is the reader's like one they made themselves: the next deploy comes from their own copy of the code, with brewless deploy or from a pipeline. Clicking the button again does not update the app, it makes a second one.
So the honest line to put next to the button in your README is: click it to see the thing run, fork it to keep up with it. A reader who wants your later fixes forks or clones the repository and deploys from there, which is what they would have done anyway, only now after they have seen it working.
What it is good for, and what it is not
A deploy button is at its best for a demo, a starter kit, a conference example or a package that is easier to show than to describe. It is a bad fit for anything that needs secrets before it does something useful: Brewless will not invent a payment key or a mail provider for the reader, and an app that fails on its first request is a worse advertisement than no button at all.
If your example does need configuration, say so right under the button and keep the list short. A demo that runs on nothing but a database and shows something real on the first page beats a complete app that wants ten variables before it answers.
There is one more thing worth knowing about the shape of the app your reader ends up with. The containers are serverless, and web.min is 0 unless your file says otherwise, so a copy of your demo that nobody visits scales back to zero instead of running on. That is a real difference from a deploy button that parks a virtual machine in someone's account and leaves it there.
Summary
- Put one markdown line in your README with your repository after
repository=. - Commit a
brewless.ymlso the environment matches what your app needs, instead of the default. - Leave
servicesout of it, or the button cannot deploy the repository. - Tell readers the button is for trying it, and a fork is for following it.
The deploy button page in the documentation has the details, including exactly which parts of your file carry over.
Frequently asked questions
What does the Deploy to Brewless button actually deploy?
The newest commit of the repository's default branch. Brewless reads that commit's composer.json to check it requires laravel/framework, and its brewless.yml if there is one. The build job in the reader's own Scaleway project then downloads the archive of that commit from the code host itself.
Which code hosts does the button work with?
GitHub, Codeberg and GitLab, as long as the repository is public. Write the address after repository= as github.com/owner/name, codeberg.org/owner/name or gitlab.com/group/name. On GitLab a project in a subgroup works too.
Does my code pass through Brewless when someone clicks the button?
No. Brewless fetches two small files from the code host to work out what to build. The source archive goes from the code host straight to the build job running in the reader's own Scaleway project.
Can the button deploy a private repository?
No. It reads public repositories only, through the code host's public API without a key. For a private repository, deploy with the command line or from a pipeline.
Does the reader need a Scaleway account before clicking?
Yes. Deploying takes a connected Scaleway project and the right to manage applications in their Brewless organisation.