Supplemental Guide: Docker LIPI - Managing Restarts and Updates

About

This guide provides instructions for managing the restarting and updating the LIPI Docker container. It emphasises the responsibility for the setup and ongoing maintenance, explaining the scenarios that require restarts, including changes to configuration or certificate renewals.

Options are provided for both manual and automated updates, to ensure smooth operation of the LIPI server.

Page Contents

2. Prerequisites

Before proceeding, ensure the following prerequisites are met:

1. Configured LIPI Docker Container:

   • A LIPI Docker container is already installed, configured, and running on your server.

2. Access to the Docker Server:

   • Admin-level access to the server hosting the Docker container.

3. Basic Understanding of Bash and Cron (Optional):

   • While not strictly required, familiarity with bash scripting and cron scheduling can be helpful for automation.

3. Reasons for Restarting the LIPI Container

A restart of the LIPI container is necessary whenever the following changes are made or occur:

1. SSL Certificate Renewal:

   • What is it?
     The LIPI server uses SSL certificates to establish secure (encrypted) communication between the server and user devices.

   • How does it work?
     These certificates validate the server’s identity and ensure data privacy during transmission.

   • When does it need a restart?
     SSL certificates are renewed automatically by MazeMap. However, the LIPI container must be restarted to load the new certificate and apply it to the server’s connections. Without a restart, the renewed certificate will not take effect, and the server may continue using an expired one, potentially causing connectivity or security issues.

2. LIPI API Key: If the API key in the MazeMap Admin Tool changes.

3. Mazepos Subdomain: Updates to the subdomain configuration.

4. Resolver Config: Modifications to DNS resolvers for the LIPI server.

5. Cloud Positioning Service Hostname or Port: Changes to the positioning service URL or port.

4. Updating the LIPI Docker Image

Updates should occur at least every two months to ensure the latest features and security fixes are applied. The following methods are available:

4.1 Manual Updates

Using Commands

Perform manual updates step by step with these commands:

1. Pull the Latest Docker Image:

   sudo docker pull gcr.io/mazemap-public-docker/proxy-lipi:latest

    

2. Stop and Remove the Existing Container:

   sudo docker rm -f proxy-lipi

    

3. Start the Updated Container:

   sudo docker run --detach --restart=always --name proxy-lipi \ --env-file=lipi-docker-env-file \ -p 443:4343 \ gcr.io/mazemap-public-docker/proxy-lipi:latest

Using a Bash Script

Simplify manual updates with a script:

1. Create a file named update-lipi.sh:

2. Make the script executable:

    

3. Run the script:

    

4. Check that the LIPI is running.

4.2 Automating LIPI Updates

Using Cron Jobs

Schedule automatic updates with cron to pull the latest Docker image and restart the container periodically.

1. Open the cron configuration file:

    

2. Add the following line to update and restart the container the first Sunday of the month @ at 3:00 AM:
   
   

5. Restarting the LIPI for Configuration Updates

MazeMap suggests automated restarts, but manual restarts may be needed if updates occur out of sequence or if automation is not configured.

5.1 Automating LIPI Restarts

Automate restarts with cron jobs or with any other task scheduling tool.

Weekly Restart Example

1. Open the cron configuration file:

    

2. Add this line to restart the container weekly:

Bi-Monthly Restart Example

For a bi-monthly schedule (1st and 15th of each month), use:

1. Open the cron configuration file:

    

2. Add this line to restart the container weekly:

    

5.2 Manual Restarts

If a manual restart is needed, follow these steps:

1. Stop and Remove the Existing Container:

2. Start the LIPI Container:

6. Command Explanation

• sudo docker pull: Downloads the latest version of the LIPI image.

• sudo docker rm -f: Forcefully stops and removes the running container.

• sudo docker run: Starts a new container with the specified environment and settings.

  • --detach: Runs the container in the background.

  • --restart=always: Ensures the container restarts automatically after failures or system reboots.

7. Verification Steps Post-Restart or Update

After restarting or updating the LIPI container, perform the following steps to verify it is running correctly and the system is functioning as expected:

1. Check the Running Container
   Ensure the LIPI container is active and running:

   This shows all of the docker containers running.
   
   

2. Test the LIPI Health Endpoint

   Verify the LIPI container’s health status:

    

3. Run the LIPI Debug Test
   Visit the MazeMap LIPI test tool at: https://debug.mazemap.com/lipi/

   • This tool runs a set of diagnostic tests on the LIPI server to ensure proper configuration and connectivity.

   • Follow the on-screen instructions to identify any issues and confirm that the LIPI server is functioning as expected.
     
     

4. Test Positioning on a Device
   Using a device connected to the Wi-Fi network that is providing :

   1. Open the MazeMap maps - https://use.mazemap.com

   2. Click the positioning button to activate positioning.

   3. Confirm that positioning is working correctly by checking if your device’s location is displayed accurately on the map.

       

8. Best Practices

• Schedule Restarts: Regular restarts ensure configuration updates are applied.

• Secure Credentials: Keep API keys and sensitive configuration files secured.

• Monitor Health: Check the container’s health periodically to detect potential issues early.

9. Contact Information

For further assistance or if you encounter any issues, please contact your IT department or MazeMap Support or log a MazeMap Support Ticket:
https://mazemap.atlassian.net/servicedesk/customer/portal/1