How to install Landscape Server with quickstart mode

The quickstart mode of deploying Landscape consists of installing all the necessary software on a single machine. Quickstart mode has limited scalability, so it may not be ideal for large production deployments.

Note that Quickstart installations and upgrades to Landscape 26.04 LTS are not supported on Ubuntu 26.04. You must use Ubuntu 24.04 LTS or 22.04 LTS for Quickstart installations.

If you’re new to Landscape and want to learn how it works first, see the Getting started with Landscape tutorial, which creates a test environment.

Check minimum requirements

The following minimum requirements are needed to install Landscape Server 24.04 LTS or 26.04 LTS:

  • Operating system: Ubuntu 22.04 LTS (Jammy Jellyfish) or Ubuntu 24.04 LTS (Noble Numbat)

  • Hardware: A dual-core 2 GHz processor, 8 GB of RAM, and 20 GB of disk space

  • Networking: An IP address and FQDN with TCP communication allowed for SSH (typically port 22), HTTP (port 80), and HTTPS (port 443)

  • If you plan to use Lets Encrypt to obtain an SSL certificate, DNS administration access for the hostname you’ll use to access Landscape

Install Landscape Server

Install prerequisites

To install prerequisites, run:

sudo apt update && sudo apt install -y ca-certificates software-properties-common

The add-apt-repository command line utility is necessary to add the PPA which contains the Landscape Server software. The software-properties-common package must be added to access add-apt-repository.

Set environment variables

To set the necessary environment variables, run:

HOST_NAME=<HOST_NAME>
DOMAIN=<DOMAIN_NAME>
FQDN=$HOST_NAME.$DOMAIN

This code block includes the following values that must be changed:

<HOST_NAME>: The host name you’re using for the Landscape installation

<DOMAIN_NAME>: The domain name you’re using for the Landscape installation

It’s important to set HOST_NAME, DOMAIN and FQDN correctly prior to installing Landscape Server. These variables are used by other commands later.

Set the machine’s host name

To set the machine’s host name, run:

sudo hostnamectl set-hostname "$FQDN"

When Landscape Server is installed, it’ll read the machine’s host name and use it in the Apache configuration.

If your FQDN does not resolve to a public IP, you will need to ensure it resolves on the machine that you are installing Landscape Server. To do so, you can run the following command:

echo "127.0.1.1 $FQDN" | sudo tee -a /etc/hosts

Attach your Ubuntu Pro token

If you have an Ubuntu Pro subscription, attach your Pro token to the server machine. For guidance, see How to attach your Ubuntu Pro subscription.

Install landscape-server-quickstart

To install landscape-server-quickstart:

  1. Add the PPA for Landscape Server, replacing <LANDSCAPE_PPA> with the appropriate repository:

    sudo add-apt-repository -y <LANDSCAPE_PPA>

    <LANDSCAPE_PPA>: The PPA for the specific Landscape installation you’re using. The PPA for the most recent recommended Landscape LTS is: ppa:landscape/self-hosted-26.04. The PPA for Landscape’s stable rolling release is: ppa:landscape/latest-stable. We recommend using an LTS for production deployments.

  2. Update packages and dependencies in your local system:

    sudo apt-get update

  3. Install landscape-server-quickstart:

    sudo DEBIAN_FRONTEND=noninteractive apt-get install -y landscape-server-quickstart

    • This installation takes approximately five minutes.

Install additional services

Select your Landscape Server version:

Install the task handler snap

Install the landscape-task-handler snap.

sudo snap install landscape-task-handler

Create the task handler’s own database and grant the landscape user access to it.

sudo -u postgres createdb landscape-standalone-task-handler
sudo -u postgres psql landscape-standalone-task-handler -c \
  "GRANT CONNECT ON DATABASE \"landscape-standalone-task-handler\" TO landscape;"
sudo -u postgres psql landscape-standalone-task-handler -c \
  "GRANT CREATE ON SCHEMA public TO landscape;"

Configure the snap to connect to the task handler database. Replace <DB-PASSWORD> with the landscape database user’s password, found in the password key of the [stores] section of /etc/landscape/service.conf. This value may be stored as plain text or, if prefixed with b64:, as base64-encoded text; in the latter case, decode it (for example, echo '<value-without-b64-prefix>' | base64 -d) to get the plaintext password. For the main, account, and resource databases this decoding happens automatically, but it must be done manually here because the task handler’s own database is not read from service.conf.

sudo snap set landscape-task-handler \
  landscape.database.task-handler.host=localhost \
  landscape.database.task-handler.port=5432 \
  landscape.database.task-handler.name=landscape-standalone-task-handler \
  landscape.database.task-handler.user=landscape \
  landscape.database.task-handler.password=<DB-PASSWORD> \
  landscape.database.task-handler.ssl=disable \
  landscape.task-handler.server.grpc-port=50053 \
  landscape.task-handler.server.host=localhost

See also

This example uses ssl=disable because Quickstart mode runs PostgreSQL on the same machine. If your PostgreSQL connection requires SSL, see Configuring SSL/TLS for PostgreSQL connections.

Important

If you change landscape.task-handler.server.host or landscape.task-handler.server.grpc-port from the defaults shown above, you must also update the outbox’s landscape.task-handler.grpc-address snap key to match. Otherwise the outbox’s services will still report as active, but hard deletion requests will fail at runtime. See Task handler client settings for details.

landscape-task-handler is configured to work automatically with an existing Landscape Server by default. Confirm that the snap service is running.

sudo snap services landscape-task-handler

The output should show the landscape-task-handler.server and landscape-task-handler.worker services as active:

Service                        Startup  Current  Notes
landscape-task-handler.server  enabled  active   -
landscape-task-handler.worker  enabled  active   -

Other services (cert-renewer, cleanup) run on their own timers and normally show as inactive/timer-activated between runs; this is expected.

To view task handler logs, run:

sudo snap logs landscape-task-handler -n 50

Install the outbox snap

Install the landscape-outbox snap on the same machine as your Landscape Server installation.

sudo snap install landscape-outbox
sudo snap connect landscape-outbox:grpc-client-certs landscape-task-handler:grpc-client-certs

landscape-outbox is configured to work automatically with an existing Landscape Server by default. Confirm that the snap service is running.

sudo snap services landscape-outbox

The output should show the outbox service as active:

Service                  Startup  Current  Notes
landscape-outbox.outbox  enabled  active   -

To view outbox logs, run:

sudo snap logs landscape-outbox -n 50

Install the Debarchive snap

The landscape-debarchive snap is required for repository management from Landscape 26.04 LTS onwards. Follow the instructions in the dedicated guide.

These service installation steps apply to Landscape 26.04 LTS and later only. Continue to the next step.

Install an SSL certificate

Note

If you have the fullchain.pem and privkey.pem files for your SSL certificate, skip these steps and configure Apache manually. For more details, see how to configure the web server in the Landscape manual installation guide.

Install Certbot

Certbot is a command line utility which makes acquiring and renewing SSL certificates from Let’s Encrypt an easy, free, and automated process. You can install Certbot with the snap or apt package manager.

To install Certbot with snap:

sudo snap install certbot --classic

Or apt:

sudo apt-get install certbot python3-certbot-apache -y

Get an SSL certificate from Let’s Encrypt

If your Landscape instance has a public IP, and your FQDN resolves to that public IP, run the following to get a valid SSL certificate from Let’s Encrypt:

sudo certbot --non-interactive --apache --no-redirect --agree-tos --email <[email protected]> --domains $FQDN

Replace <EMAIL@ADDRESS.COM> with an email address where certificate renewal reminders can be sent.

Create a global administrator account

At this point, visiting https://$FQDN prompts you to create Landscape’s first Global Administrator account. To add administrators:

  1. Click Settings

  2. Set a valid outgoing email address in the System email address field

  3. Click Save

By default, the email address will be pre-filled with noreply@HOST_NAME.DOMAIN. You may want to change this to noreply@DOMAIN, or another valid email address.

(Optional) Configure Postfix for email

You can configure Postfix to handle Landscape Server email notifications and alerts. For details, see How to configure Postfix for emails.

Next step: Register your clients

Your Landscape server is now ready to manage client instances. To register clients:

  1. See How to install Landscape Client for instructions on installation and registration.

  2. When registering clients, attach an Ubuntu Pro token to each client machine to enable Pro services. If you don’t have a token, you can get a free personal Ubuntu Pro subscription at ubuntu.com/pro.

For more details, see How to attach your Ubuntu Pro subscription and How to enable Landscape in the Ubuntu Pro Client.