Deploy a Beego App

This guide explains how to deploy a basic Beego (opens in a new tab) application to Koyeb using:

  1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
  2. Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Express application from this guide by clicking the Deploy to Koyeb button below.

Deploy to Koyeb (opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Beego app

We will begin by creating a basic Beego application. You will need a recent version of Go (opens in a new tab) installed on your local machine. Make sure that your GOPATH is configured (opens in a new tab) and that your PATH includes $GOPATH/bin so that you can execute Go binaries. Additionally, you may wish to install Docker (opens in a new tab) if you are planning on building and testing a container image for the application locally.

Install the bee tool

To get started, install Beego's bee command line tool (opens in a new tab) on your local computer. The bee command can be used to initialize Beego projects, manage scripts, and run development servers. Install it by typing:

go install

You can verify that bee is installed and accessible in your PATH by typing:

bee version

Create a new Beego project and install dependencies

Once bee is installed, you can use it to create a new project by typing:

bee new example-beego

This will create a new directory called example-beego containing a starter project. Enter the new directory by typing:

cd example-beego

Inside, you should see a conventional MVP application (opens in a new tab) structure:

├── conf
│   └── app.conf
├── controllers
│   └── default.go
├── go.mod
├── main.go
├── models
├── routers
│   └── router.go
├── static
│   ├── css
│   ├── img
│   └── js
│       └── reload.min.js
├── tests
│   └── default_test.go
└── views
    └── index.tpl

The primary entry point for the application is main.go, but the core functionality is found in the controller, routers, models, and views directories. You can modify the application configuration with the conf/app.conf file.

In the project root directory, install the required dependencies by typing:

go mod tidy

This will resolve the dependency graph of the required modules and install all of the necessary packages.

Test the application

We can run application that the bee new command generated by typing:

bee run

This will start up a development server. Visit http://localhost:8080 in your web browser to view the standard Beego landing page, indicating that the application is running as expected.

Press CTRL-C when you are finished to stop the development server.

Modify the configuration

By default, the application is configured to run on port 8080. Koyeb automatically sets the PORT environment variable to the port it exposes traffic to. We will configure the application to listen on the port defined by the PORT variable to ensure that these two layers are in sync.

Open the conf/app.conf file in your editor. Inside, modify the value of the httpport option like this:

appname = example-beego
httpport = "${PORT||8000}"
runmode = dev

Here, we set the value of httpport to "${PORT||8000}". This will cause Beego to set httpport to the value of the PORT environment variable. If no PORT variable is found, Beego will use port 8000 as a fallback value.


Note: Do not include spaces in the httpport value. Spaces are not permitted in the definition and will cause the value to be misinterpreted.

You can test this new functionality by starting the development server again. First, without a PORT value defined:

bee run

This will start up the development server on port 8000.

If you run it with the PORT variable defined, the server should listen to the configured port as expected:

PORT=5555 bee run

This time, the server should run on port 5555.

Create a Dockerfile for the project (Optional)

We can build and run our Beego project on Koyeb using the native Go buildpack, but we can also optionally build from a Dockerfile for more control. To make it possible to build a container image for our application, we just need to create the Dockerfile. We'll also define a .dockerignore file to tell the builder what files to skip when creating the image.

While the bee command does include a dockerize subcommand, the Dockerfile it generates is over 1GB for the example application. We can provide a more optimized build by creating our own Dockerfile.

First, define a .dockerignore file in your main project directory. Inside, paste the following contents:


This file tells Docker to not include Git files, the Docker files themselves, and the example-beego binary itself if it is present. This helps ensure that the image we build is not bloated and that the build completes faster.

Next, create a new file called Dockerfile within the main project directory. Inside, paste the following contents:

# Build stage
FROM golang:1.20.2 AS builder
COPY . .
RUN go mod tidy -v && CGO_ENABLED=0 go build -v -o /app/example-beego
# Run stage
FROM scratch AS runner
COPY --from=builder /app/example-beego .
COPY --from=builder /app/conf ./conf
COPY --from=builder /app/views ./views
COPY --from=builder /app/static ./static
EXPOSE "${PORT:-8000}"
CMD ["/app/example-beego"]

This Dockerfile uses a multistage build (opens in a new tab) to separate the build steps from the final image environment. This creates a more streamlined image and allows us to tightly control what files are included in the final image.

The first stage is based on official Go image on Docker Hub (opens in a new tab). Check the go.mod file for the version of Go your project is build against and choose a compatible Docker image to ensure that it builds correctly.

The build stage sets up a working directory and then copies the application code to the image filesystem. Afterwards, it calls go mod tidy to install the dependencies and then compiles the binary with go build. In this case, we use the CGO_ENABLE environment variable (opens in a new tab) to make sure that the compiled binary isn't dynamically linked to any C files that won't be available on the second stage filesystem.

The second stage is based on the bare-bones scratch image (opens in a new tab). We copy the compiled binary along with some other files (opens in a new tab) not included in the binary that Beego needs to operate correctly. We configure the PORT environment variable so that we can dynamically adjust the port and call the binary then run the binary directly.

If you have Docker installed locally, you can build and test the image on your computer and optionally upload it to a registry. You can deploy container images from any container registry to Koyeb.

We can also build the Dockerfile directly from the repository when we deploy, which is useful as a way of automatically deploying when changes occur. We will demonstrate this method as one of the options in this guide.

Push the project to GitHub

In the project directory, initialize a new git repository by running the following command:

git init

Next, download a basic .gitignore file designed for Go projects from GitHub:

curl -L -o .gitignore

Add the example-beego binary that the bee run command produces to the .gitignore file by typing:

echo "example-beego" >> .gitignore

Once you're ready, add the project files to the staging area and commit them. If you don't have an existing GitHub repository to push the code to, create a new one (opens in a new tab) and then run the following commands to commit and push changes to your GitHub repository:

git add :/
git commit -m "Initial commit"
git branch -M main
git push -u origin main

Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Deploy to Koyeb using git-driven deployment

Once the repository is pushed to GitHub, you can deploy the Beego application to Koyeb. Any changes in the deployed branch of your codebase will automatically trigger a redeploy on Koyeb, ensuring that your application is always up-to-date.

To deploy the Beego app on Koyeb using the control panel (opens in a new tab), follow the steps below:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public Beego example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page:
  4. Choose the Builder for your project. We can use either a Dockerfile or buildpack for this repository.
  5. Name your Service, for example beego-service.
  6. Name the App, for example example-beego.
  7. Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

Deploy to Koyeb from a container registry

If you chose to build a container image for the Beego application, you can optionally deploy the application from a container registry instead of from GitHub.

To deploy a pre-built Beego container image on Koyeb using the control panel (opens in a new tab), follow the steps below:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select Docker as the deployment option.
  3. Choose the container image and tag from your registry and click Next to continue.
  4. Name your Service, for example beego-service.
  5. Name the App, for example example-beego.
  6. Click the Deploy button.

A Koyeb App and Service will be created. The container image will be pulled from the container registry and a container will be deployed from it. Once the initialization is complete, you will be able to access your application running on Koyeb by clicking the URL ending with