maas-base/docs/installation/installation.md

Installation

Prerequisites

MaaS-Base server:

• Docker must be installed. Docker Desktop (Windows and macOS) is also supported.

MaaS-Base workers:

• Docker must be installed. Docker Desktop is not supported.
• Only Linux is supported for MaaS-Base worker nodes. If you use Windows, consider using WSL2 and avoid using Docker Desktop. macOS is not supported for MaaS-Base worker nodes.
• Ensure the appropriate GPU drivers and container toolkits are installed for your hardware. See the Installation Requirements for details.

Install MaaS-Base Server

Run the following command to install and start the MaaS-Base server using Docker:

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    --volume gpustack-data:/var/lib/gpustack \
    gpustack/gpustack

!!! note

MaaS-Base v2 uses a single unified container image for all GPU device types.

Startup

Check the MaaS-Base container logs:

sudo docker logs -f gpustack

If everything is normal, open http://your_host_ip in a browser to access the MaaS-Base UI.

Log in with username admin and the default password. Retrieve the initial password with:

sudo docker exec -it gpustack \
    cat /var/lib/gpustack/initial_admin_password

Add GPU Clusters and Worker Nodes

Please follow the UI instructions on the Clusters and Workers pages to add GPU clusters and worker nodes.

Custom Configuration

The following sections describe examples of custom configuration options when starting the MaaS-Base server container. For a full list of available options, refer to the CLI Reference.

Enable HTTPS with Custom Certificate

 sudo docker run -d --name gpustack \
     ...
     -p 80:80 \
+    -p 443:443 \
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/cert_files:/path/to/cert_files:ro \
+    -e GPUSTACK_SSL_KEYFILE=/path/to/cert_files/your_domain.key \
+    -e GPUSTACK_SSL_CERTFILE=/path/to/cert_files/your_domain.crt \
     gpustack/gpustack
     ...

Using an External Database

By default, MaaS-Base uses an embedded PostgreSQL database. To use an external database such as PostgreSQL or MySQL, set the GPUSTACK_DATABASE_URL environment variable or use the --database-url argument when starting the MaaS-Base container:

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    -e GPUSTACK_DATABASE_URL="postgresql://username:password@host:port/dbname" \
     gpustack/gpustack
     ...

Configure External Server URL

If you use a cloud provider to provision workers, set the external server URL for worker registration to ensure that workers can connect to the server correctly.

sudo docker run -d --name gpustack \
    ...
+   -e GPUSTACK_SERVER_EXTERNAL_URL="https://your_external_server_url" \
    gpustack/gpustack
    ...

Additional Trusted CAs

If MaaS-Base needs to communicate with services that use certificates issued by a private or corporate CA (e.g., a self-hosted Identity Provider, a Hugging Face mirror, or an internal API endpoint), mount the CA certificate into the container under /usr/local/share/ca-certificates/. MaaS-Base will automatically import the mounted CA certificates during startup and add them to the system trust store.

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/custom-root-ca.crt:/usr/local/share/ca-certificates/custom-root-ca.crt:ro \
     gpustack/gpustack
     ...

!!! note

The certificate file must have a `.crt` extension. You can mount multiple CA certificates by adding additional `--volume` flags.

Installation via Docker Compose

Prerequisites

• Docker Compose must be installed.
• Required ports must be available.

Deployment

The Docker Compose files and configuration files are maintained in the GPUStack repository.

Run the following commands to clone the latest stable release:

LATEST_TAG=$(
    curl -s "https://api.github.com/repos/gpustack/gpustack/releases" \
    | grep '"tag_name"' \
    | sed -E 's/.*"tag_name": "([^"]+)".*/\1/' \
    | grep -Ev 'rc|beta|alpha|preview' \
    | head -1
)
echo "Latest stable release: $LATEST_TAG"
git clone -b "$LATEST_TAG" https://github.com/gpustack/gpustack.git
cd gpustack/docker-compose

Start the MaaS-Base server:

sudo docker compose -f docker-compose.server.yaml up -d

If everything is normal, open http://your_host_ip in a browser to access the MaaS-Base UI.

Log in with username admin and the default password. Retrieve the initial password with:

sudo docker exec -it gpustack-server cat /var/lib/gpustack/initial_admin_password

For built-in and external observability options, see Observability.