Quickstart Guide: Run & Test Your Prototype With Docker

Hey guys! This guide will walk you through getting the prototype up and running on your machine using Docker Desktop. We've kept it super simple so you can dive right into testing without needing a developer on standby. Let's get started!

Prerequisites

Before we jump in, make sure you have Docker Desktop installed. If not, head over to the Docker website and download it for your operating system. Follow the installation instructions provided on the site. Once Docker Desktop is up and running, you should see the Docker icon in your system tray. Also, ensure that your system meets the minimum requirements for running Docker Desktop, including sufficient memory and disk space. Keep your Docker Desktop updated. Newer versions often include performance improvements and bug fixes that can streamline your experience. Configuring resource limits in Docker Desktop settings helps optimize performance, especially when running other applications simultaneously. Docker Desktop can sometimes conflict with other virtualization software, so ensure compatibility or disable conflicting programs temporarily. If you encounter any issues during installation, consult the official Docker documentation or seek assistance from online forums and communities dedicated to Docker support. Verify that Docker Desktop is properly integrated with your system by running basic Docker commands in your terminal or command prompt. This will confirm that Docker is accessible and functioning correctly.

Step-by-Step Instructions

These easy-to-follow steps will get your prototype up and running in no time.

1. Unzip the Package

First things first, locate the package we sent you (it's probably named something like CONDO-020-prototype.zip). Unzip the entire contents of this file to a location on your computer where you can easily find it, like your Documents folder or a dedicated Prototypes directory. Make sure you extract all files and folders within the ZIP archive to ensure the application runs correctly. Verify that the extracted directory contains the necessary files, including docker-compose.yml and other related configuration files. Avoid extracting the ZIP archive directly into a system directory or a location with restricted access, as this may cause permission issues. If you encounter any errors during the extraction process, try using a different ZIP extraction tool or redownload the package to ensure it is not corrupted. Double-check that the file paths and directory structure are preserved during extraction, as incorrect paths can lead to application failures. Consider using a file archiver with integrity check features to verify the integrity of the extracted files. This will help prevent potential issues caused by incomplete or corrupted extractions.

2. Navigate to the Directory

Open your terminal or command prompt. On Windows, you can use PowerShell or Command Prompt. On macOS or Linux, use the built-in Terminal application. Use the cd command to navigate to the directory where you unzipped the package. For example, if you unzipped it to Documents/CONDO-020-prototype, you'd type:

cd Documents/CONDO-020-prototype

Make sure you type the directory name correctly! Autocomplete (using the Tab key) can be your best friend here. Verify that the directory you are navigating to actually exists and contains the necessary files, such as docker-compose.yml. If you encounter a "directory not found" error, double-check the path you entered and ensure it matches the actual directory structure. Use the ls (or dir on Windows) command to list the contents of the current directory and confirm that you are in the correct location. Avoid using relative paths if you are unsure of your current working directory, as this can lead to navigation errors. If you are working with a network drive or shared folder, ensure that you have the necessary permissions to access the directory. Consider creating a symbolic link or shortcut to the directory for easier access in the future. This can save you time and effort when navigating to the directory repeatedly.

3. Start the Stack

Now for the magic! With your terminal in the correct directory, run the following command:

docker-compose up

This command tells Docker Compose to build and start all the services defined in the docker-compose.yml file. You'll see a bunch of output scrolling through your terminal as Docker pulls images, creates containers, and starts everything up. Be patient; the first time you run this, it might take a few minutes to download all the necessary images. Watch the terminal output closely for any error messages that may indicate issues with the startup process. If you encounter errors, refer to the troubleshooting section below or consult the application's documentation. Once the docker-compose up command completes successfully, all the necessary services should be running in Docker containers. You can verify the status of the containers by running the docker ps command in your terminal. Ensure that the required ports are properly exposed and mapped to the host machine. If you need to restart the stack, use the docker-compose down command to stop the containers and then run docker-compose up again. Consider using the -d flag with the docker-compose up command to run the containers in detached mode, allowing you to continue using the terminal for other tasks.

4. Access the UI

Once the docker-compose up command finishes without errors, the application should be accessible in your web browser. Usually, the UI is available at http://localhost:3000 or http://localhost:8080. Check the docker-compose.yml file or the application's documentation to confirm the correct URL. If you're using a different port, make sure to include that in the URL (e.g., http://localhost:8081). If you can't access the UI, give it a minute or two – sometimes it takes a little while for everything to fully initialize. Also, double-check that Docker Desktop is still running! Verify that the application is properly configured to listen on the specified port and that there are no firewall rules blocking access. If you are using a virtual machine or remote server, ensure that the necessary port forwarding rules are in place. Try clearing your browser cache and cookies or using a different browser to rule out any browser-related issues. If the application is running behind a reverse proxy, ensure that the proxy is properly configured to forward requests to the correct backend server. Consider using a network monitoring tool to check for any network connectivity issues between your machine and the application server. This can help identify potential problems with routing, DNS resolution, or firewall settings.

5. Log In

Use the following demo credentials to log in and explore the core screens:

• Username: demo
• Password: password123

These credentials should give you access to all the main features of the prototype. Don't worry; you can't break anything! If these credentials don't work, double-check with the development team to ensure they haven't been updated. Verify that the login form is properly configured and that the authentication service is running correctly. If you encounter issues with the demo credentials, try clearing your browser cache and cookies or using a different browser. If the application uses a database, ensure that the database is properly seeded with the necessary demo data. Consider using a debugging tool to inspect the login process and identify any potential errors or authentication failures. If you are working with a multi-user environment, ensure that the demo credentials are not being used by multiple users simultaneously, as this may cause conflicts or unexpected behavior. Regularly update the demo credentials to prevent unauthorized access or misuse.

Troubleshooting

Okay, sometimes things go wrong. Here are some common issues and how to fix them.

• Ports Already in Use: If you see an error about ports being in use, it means another application on your machine is using the same port that the prototype needs. The easiest fix is to stop the other application. You can also try changing the port in the docker-compose.yml file, but that's a bit more advanced. To identify which application is using the port, use the netstat command (on Windows) or lsof command (on macOS/Linux). Ensure that the port specified in the docker-compose.yml file matches the port that the application is configured to listen on. If you are running multiple instances of the application, make sure that each instance is using a unique port. Consider using a port management tool to dynamically assign ports to the application and avoid conflicts. If you are running the application in a containerized environment, ensure that the necessary port mappings are configured correctly. Regularly monitor the port usage on your system to identify and resolve potential port conflicts.
• Volumes Not Mounting: If the application can't access certain files or directories, it might be a problem with volume mounting. Double-check the docker-compose.yml file to make sure the volumes are defined correctly and that the paths exist on your machine. Ensure that the user running the Docker container has the necessary permissions to access the mounted volumes. If you are using relative paths for volume mounts, make sure that the paths are relative to the docker-compose.yml file. Consider using absolute paths for volume mounts to avoid ambiguity and potential errors. If you are using a network file system for volume mounts, ensure that the network share is properly mounted and accessible. Regularly check the volume mounts to ensure that they are functioning correctly and that data is being persisted as expected.
• Missing Environment Variables: The application might rely on certain environment variables to be set. If you see errors related to missing environment variables, make sure you've created a .env file in the same directory as the docker-compose.yml file and that it contains all the required variables with their correct values. Verify that the environment variables are properly defined in the docker-compose.yml file or in the .env file. Ensure that the environment variables are being passed to the Docker container correctly. If you are using a secrets management tool, make sure that the secrets are properly injected into the application's environment. Consider using a configuration management tool to manage and deploy environment variables across different environments. Regularly review and update the environment variables to ensure that they are accurate and up-to-date.
• Docker not enough resources: If the application errors or stops, then increase the memory.

FAQ

• Where can I find the logs?

The application logs are usually written to the console, so you'll see them in your terminal window where you ran the docker-compose up command. You can also configure the application to write logs to a file if needed. Check the application's documentation for details on how to configure logging. If you are using a logging framework, ensure that it is properly configured and that the logs are being written to the desired location. Consider using a centralized logging system to collect and analyze logs from multiple sources. Regularly monitor the logs to identify and resolve potential issues.

• How do I stop the stack?

To stop all the containers, navigate to the same directory where you ran the docker-compose up command and run:

docker-compose down

This will stop and remove all the containers created by the docker-compose.yml file.

That's It!

You should now have the prototype up and running. Have fun testing! And remember, if you get stuck, don't hesitate to reach out to the development team. We're here to help!