Techies.

How do I view my app?

This article guides you through the process of getting your app running on your local machine using Docker.


Currently, the only way to see your app actually running is to run it on your local computer (or release it). In order to view your application on your computer, you will need to complete three steps:

The whole process should take less than 30 minutes to setup the first time. Once you have done it, it only takes a few minutes to get a different app running.

If you have any issues with these instructions, please let us know. We are doing our best to make them as accessible as possible, but we can’t get better without your feedback. To get in touch, just use the support link in the menu.


Step 1: Getting the code onto your computer

To get the code onto your computer, you will need to use Git to copy it down.

If you are a developer, you will most likely have Git already on your computer, setup according to your personal preferences. If this is the case, you can skip straight to setting up your repos.

What is Git?

Git is how you and the bots can work together side by side. You can use Git to access your source code and edit it, commit your changes, then update the diagrams and get the bots to build again, without losing your progress.

Think of it like a storage space / file system up the cloud which both you and the bots can work with at the same time. Git can help you identify who changed what, when, and help ensure you don’t overwrite each other.

Git helps with this by copying all of the source files down onto your machine. From there you can edit them, upload your changes, or download any new changes the bots have made as needed.

  • For more information on the basics of Git, you can look at any number of articles on the web. (We are fond of this one).
  • For more information on how the bots work with Git, read Codebots and git (written for techies).

Downloading a Git Client

If you don’t already have Git on your computer, getting a Git client is the first thing you will need to do. There are many different Git clients that you could use to manage Git on your computer. If you are in a tech company or a company with developers, they might have a preference for which one you use. If this is the case, ask them for their recommendations/assistance with this process.

If you have no preferences, then we recommend you use GitFiend. It is freely available on Mac, Windows, and Linux, and has a very simple interface. It suits our purposes quite nicely.

Go to the home page of the GitFiend website and download it for your computer. Run the install like you normally would any other app.

Setting up your repo

Each application you make on the Platform will have its own repository associated with it (meaning that if you have multiple apps, you will need to clone multiple repositories). The Git details of your currently selected app are available in your app’s settings page (located on the Dashboard). Your login details will be your Codebots account details, unless you changed your Git login at any point. The username is shown on the Git details page.

If you did not use our recommended Git client, then you will need to rely on documentation or someone else’s assistance for this part.

Follow the below instructions, or skip to the video at the end.

  1. Choose where on your computer you want the files to be saved, and create a folder to contain your app(s).
    For this demonstration, we will be creating a file called Codebots in the Documents folder. This will hold all the Codebots apps we want to run.
  2. Open up GitFiend and click the ‘Clone a Repo button’.
    Alternatively, you can go to the ‘Open…’ button at the top of the app and choosing the ‘Clone Repository’ option.
  3. The ‘Clone a Repo’ pop-up will display.
  4. Get your repository URL from your app’s settings page, under the Git tab.
  5. Paste the URL into the ‘URL or path’ field of the popup.
  6. Click the ‘Browse’ button next to the ‘Where to clone to field’.
  7. Navigate to the folder you made earlier where you want to save all your apps and click Open. Codebots inside Documents in this example.
  8. Click on the ‘Clone’ button.
  9. It will now ask you for authentication. Your login details will be your Codebots account details, unless you changed your Git login at any point. The username is saved on the Git details page.
  10. When you are ready, click on the OK button.
  11. If all went well, your app will begin cloning down to your computer.

Step 2: Installing the program which runs the code

In order to be able to actually run your application, you will first need to install Docker.

What is Docker?

Docker is how we are able to automate a lot of the app running process, to make it as painless as possible to work with. It means your developers can set up the environment which is required to run the app, packaging it up into a neat little container which comes with the code. All you need to do is tell it when to start and stop.

Unfortunately, the first time you will need to install the program. But once you have done it the first time, it gets significantly quicker.

Downloading & installing Docker

To download Docker, open the Docker Desktop page and click on the blue “Download for X (stable)” button at the top.

Run the file the which you have downloaded and complete the installation process. If you are using Windows, please make sure you read the linked documentation below. There are specific steps which can’t be missed and are not always obvious.

For instructions and installation requirements, you can follow the official Docker documentation:

If your computer does not meet the system requirements you will need to follow a different set of instructions to get your app building locally. See Starting the Prebuild Ubuntu 18.04 Virtual Machine for instructions on setting up a local machine.

If you ever get stuck at any point in the install process, you can refer to the Docker documentation and choose your OS for instructions and specifications. Alternatively, you can reach out to our support team via the feedback portal.

Windows Home

If you are using Windows Home, you need to be on one of the latest versions of Windows in order to be able to install Docker. You can choose to either update Windows before you start, or try the installation and see if it works.

The installation instructions are here: Windows Home instructions
Instructions on checking and updating your Windows version: Updating Windows 10

If during the installation process you see the following error message, that means you will need to update your Windows:
Image


Step 3: Running your app

  1. Make sure docker is running

    OS Instructions
    Windows It will show up in your status bar. It doesn’t start automatically after installation, so open it following these instructions.
    Mac It will show up in the status bar. To start it, open it from your applications folder.
  2. In your file browser, open to the folder that you cloned down earlier. It will be called whatever you chose to name it (i.e. ‘Fishnatics’).
  3. And navigate to the _shortcuts folder and follow the instructions for using these scripts (depending on your OS):

    OS Start Instructions Stop Instructions
    Windows Right click windows_start.ps1, click run with powershell to start the app. Right click windows_stop.ps1, click run with powershell to stop the app.
    Mac Double click mac_start.command to start the app Double click mac_start.command to stop the app
    Ubuntu Double click linux_start.sh to start the app Double click linux_stop.sh to stop the app

    This will cause a new terminal or command prompt window to open up at that selected location which will run docker.

  4. Wait as it starts up. You will see the logs to let you know when the application when the app is running and ready to go!

Opening your app

Depending on your bot, you will need to go to one of the following local URLs to view your app:

Bot URL
SpringBot http://localhost:8000
C#Bot http://localhost:8001

If you were able to run Docker successfully, you will be greeted with a login page. Depending on what user groups you set up in the Diagram, you will need different accounts to get in. There is also a super account which you can use if needed:

Username: super@example.com
Password: password

If you are unable to login despite having the correct access details, your server-side may still be starting up. Give it a few minutes and try again.


Stopping your app

If you want to stop your app running, you can press Ctrl+C (Not Cmd+C, even on a mac) while in the terminal/command window to cancel the current process. Alternatively, you can close that window, or you can kill the Docker application.


Switching to a different app

If you want to run a different app using docker, you will need to repeat the above instructions, minus the download and setup parts.

  1. Clone down the git repo
  2. Run Docker from the new folder

Since Docker runs based on the repository that is it started in, all you need to do is ensure that you have the files on your computer first.

You will need to stop the other app running before starting another one.


Useful Commands

Docker Compose command-line reference can be found here and the Docker child command reference can be found here.

Use docker-compose exec [client|server] [command] to run any command inside a running container.

General
Command Client Server
See logs docker-compose logs -f client docker-compose logs -f server
Restart docker-compose restart client docker-compose restart server
Open Shell docker-compose exec client sh docker-compose exec server sh
C#Bot
Command Code
Create Migrations docker-compose exec server dotnet ef migrations add init
Drop Database docker-compose exec server dotnet ef database drop
SpringBot
Command Code
Run Server docker-compose exec server sh -c "./gradlew bootRun"
Stop Server docker-compose exec server sh -c "pkill java"

Last updated: 27 August 2020


Related articles