Skip to main content

Self-Hosting MeterSphere

This document provides a comprehensive guide to self-hosting MeterSphere, an open-source continuous testing platform. It covers prerequisites, installation steps, configuration, and basic troubleshooting.

Prerequisites​

Before you begin the self-hosting process, ensure your environment meets the following requirements:

  • Operating System: Linux (CentOS/RHEL 7+, Ubuntu 16.04+, Debian 9+ recommended). Windows is not officially supported for production deployments.
  • Hardware:
    • Minimum: 4 CPU cores, 8 GB RAM, 50 GB storage. This is suitable for small teams and testing environments.
    • Recommended: 8+ CPU cores, 16+ GB RAM, 200+ GB storage. This is recommended for production environments. Storage requirements will vary significantly based on the number of tests, test results, and artifacts stored.
  • Software:
    • Docker: Version 20.10 or later.
    • Docker Compose: Version 1.28 or later. (Often bundled with Docker, but verify the version.)
    • Database: MySQL 5.7+ or MariaDB 10.3+. (Note: MeterSphere's documentation often uses MySQL examples)
    • (Optional but Recommended): A reverse proxy such as Nginx or Apache. This is crucial for exposing MeterSphere securely and handling SSL/TLS.

Installation​

The recommended way to install MeterSphere is using Docker Compose.

  1. Download MeterSphere's Docker Compose file:

    You can obtain the latest docker-compose.yml file and related configuration files from the official MeterSphere GitHub repository or website (check the official documentation for the correct link). It's crucial to use the docker-compose.yml file provided by MeterSphere to ensure compatibility. Typically, you'll download a directory containing files like:

    • docker-compose.yml
    • .env (Configuration file)
    • metersphere (Directory for persistent data)

  2. Configure the .env file:

    The .env file contains crucial environment variables for configuring MeterSphere. Edit this file to match your environment. Key variables to configure include:

    • MS_DB_HOST: The hostname or IP address of your MySQL/MariaDB server.
    • MS_DB_PORT: The port number of your MySQL/MariaDB server (usually 3306).
    • MS_DB_NAME: The name of the database MeterSphere will use. Create this database manually before starting the containers.
    • MS_DB_USERNAME: The username for the database.
    • MS_DB_PASSWORD: The password for the database user.
    • TZ: Timezone setting (e.g., America/Los_Angeles or UTC). Setting the correct timezone avoids display issues.
    • HTTP_PORT: The port on which MeterSphere will be accessible (e.g., 8080). Change this if port 8080 is already in use on your system.
    • HTTPS_PORT: The HTTPS Port if you enable HTTPS.

    Example .env snippet:

    MS_DB_HOST=192.168.1.10
    MS_DB_PORT=3306
    MS_DB_NAME=metersphere
    MS_DB_USERNAME=msuser
    MS_DB_PASSWORD=mypassword
    TZ=UTC
    HTTP_PORT=8080
    HTTPS_PORT=8443

  3. Create the Database:

    Before starting the containers, create the database specified in MS_DB_NAME in your MySQL/MariaDB server. Grant the user specified in MS_DB_USERNAME appropriate permissions (at least CREATE, SELECT, INSERT, UPDATE, DELETE, ALTER) on that database.

    CREATE DATABASE metersphere CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'msuser'@'%' IDENTIFIED BY 'mypassword';
    GRANT ALL PRIVILEGES ON metersphere.* TO 'msuser'@'%';
    FLUSH PRIVILEGES;

    Replace 'msuser' and 'mypassword' with the actual username and password you configured in the .env file. Also consider restricting the host '%' to a specific IP address or network for security.

  4. Start the Containers:

    Navigate to the directory containing the docker-compose.yml file in your terminal and run the following command:

    docker-compose up -d

    This command will download the necessary Docker images and start the MeterSphere containers in detached mode (running in the background).

  5. Verify the Installation:

    • Check the container logs: Use docker-compose logs -f to monitor the logs of all the containers. Look for any errors during startup. Pay attention to the metersphere container as it performs database migrations and initialization.
    • Access MeterSphere in your browser: Open your web browser and navigate to http://<your_server_ip>:<HTTP_PORT> (e.g., http://192.168.1.10:8080).

    If everything is configured correctly, you should see the MeterSphere login page. The default credentials are:

    • Username: admin
    • Password: metersphere

    Important: Change the default password immediately after logging in for security reasons.

Configuration (Post-Installation)​

After the initial installation, you'll likely need to configure MeterSphere further:

  • System Settings: Configure global settings such as email integration (for notifications), LDAP/AD integration (for user authentication), and project-specific settings.
  • Resource Pools: If you plan to run performance tests with distributed load generation, configure resource pools to manage your load agents (e.g., JMeter instances).
  • User Management: Create and manage users, assigning appropriate roles and permissions.
  • SSL/TLS Configuration (Highly Recommended): Configure a reverse proxy (Nginx or Apache) to handle SSL/TLS encryption. This is crucial for securing communication with MeterSphere, especially if it's accessible over the internet. Refer to the documentation for your chosen reverse proxy for detailed instructions. Disable HTTP access (port 8080 by default) once HTTPS is properly configured.

Common Issues and Troubleshooting​

  • Database Connection Errors: Verify that the database server is running, that the database exists, and that the credentials in the .env file are correct. Check the database server's logs for connection attempts from the MeterSphere container. Ensure that the database server is configured to accept connections from the MeterSphere host (check firewall rules and the bind-address setting in the MySQL/MariaDB configuration).
  • Container Startup Failures: Examine the container logs using docker-compose logs -f. Look for error messages that indicate the cause of the failure. Common causes include:
    • Incorrectly configured environment variables in the .env file.
    • Insufficient resources (CPU, memory).
    • Port conflicts (another service is already using the port MeterSphere is trying to use).
  • Login Issues: If you can't log in with the default credentials (admin/metersphere), there might be a database initialization problem. Try restarting the containers. If the problem persists, you may need to reset the administrator password (refer to MeterSphere's documentation for instructions on how to do this via the command line).
  • Performance Problems: Monitor the resource usage of the containers (CPU, memory, disk I/O). Increase resources if necessary. Optimize your database server configuration. Consider using a dedicated storage volume for MeterSphere's data to improve I/O performance.
  • Reverse Proxy Configuration Issues: Double-check your reverse proxy configuration (Nginx or Apache). Ensure that it is correctly forwarding requests to the MeterSphere container. Verify that SSL/TLS is properly configured. Look for errors in the reverse proxy's logs.
  • Version incompatibility: Ensure that the versions of the components (Docker, Docker Compose, MySQL/MariaDB, MeterSphere) are compatible with each other and with your operating system. Check the MeterSphere official documentation for version recommendations.

Upgrading MeterSphere​

Upgrading MeterSphere involves pulling the latest Docker images and restarting the containers. Always back up your database before performing an upgrade. Consult the official MeterSphere documentation for the recommended upgrade procedure, as it may involve specific steps or database migrations. A typical upgrade process would look like this:

  1. Backup the Database: Create a full backup of your MeterSphere database.
  2. Stop the Containers: docker-compose down
  3. Pull the Latest Images: docker-compose pull
  4. Start the Containers: docker-compose up -d
  5. Verify the Upgrade: Check the container logs for any errors. Log in to MeterSphere and verify that the upgrade was successful.

Further Reading​

  • MeterSphere Official Documentation: [Link to Official Documentation] (Replace with the actual link)
  • MeterSphere GitHub Repository: [Link to GitHub Repository] (Replace with the actual link)

This documentation is a starting point. Refer to the official MeterSphere documentation for the most up-to-date and detailed information.