Dev Kit

Tool to run local dev environments

Getting started

1. The DevKit operates under the assumption that you have a folder for all your projects, a sub-folder for each project and in that a folder for each repository / project that belongs to it

    - projects
       |- tool
       |  |-tool-api
       |  |-tool-client
       |   
       |- project2

2. Create folder for your new DevKit (in this example we call it tool-dev-kit)

   mkdir projects/tool/tool-dev-kit

3. Go into that project

   cd my-dev-kit

4. Init a npm project

   npm init

   Answer all question how you want it
5. Install the dev-kit

   npm i @rene.simon/dev-kit

6. Execute setup

   devKitSetup

   Answer all question how you want it
   • in this example we name the shell script tCtrl
7. Add your services to the services section of the docker-compose.yml

   tool-api:
      container_name: $TOOL_API_NAME
      build:
         context: $TOOL_API_LOCAL_PATH
      command: "npm run dev"
      working_dir: /app/tool-api
      volumes:
         - '$TOOL_API_LOCAL_PATH:/app/tool-api'
         - '~/.npmrc:/root/.npmrc'
      env_file:
         - .env
      environment:
         PORT: $TOOL_API_PORT
      networks:
         - net
      labels:
      healthcheck:
         test: "wget -qO - localhost:$TOOL_API_PORT/healthcheck"
         interval: 15s
         timeout: 2s
         retries: 4
         start_period: 30s
   tool-client:
      container_name: "$TOOL_CLIENT_NAME"
      image: "node:14.16.1"
      env_file:
         - .env
      volumes:
         - '$TOOL_CLIENT_LOCAL_PATH:/app/tool-client'
         - '~/.npmrc:/root/.npmrc'
      networks:
         - net
      labels:

   IMPORTANT:
   • Service names:
     Must be in param-case
     All connected variables must be prefixed with the same name as CONSTANT_CASE
   • Volumes:
     For link to work the node code as to run in a folder named like the real folder in app
     /tool/tool-api --> /app/tool-api
   • All services need to use the same network
8. Run setup again to trigger label creation
   (you can run this anytime you want to check if your environment is still up to specs)

   devKitSetup

9. You might be asked to set some missing labels for you added services
   1. Add types
      • internal: Defines that this is a service that is developed by you.
        Most functions of the dev kit are only allowed for internal services.
      • node: All services that are node projects and should be marked as such
      • tool: Marks services that are tool projects like DBs
      • server: Services that run as servers.
      • linkSource: service project can be linked to another service
      • linkTarget: service can have another service linked too
   2. Add dependencies
      • Services that should run before this service runs
      • Usually these are dbs
   3. Add openUrl
      • Url that is opened when the open action is used
      • Environment variables are allowed
10. Configure environment
    1. You need to add ${SERVICE_NAME}_REPO and ${SERVICE_NAME}_LOCAL_PATH for each internal project
    2. Service name is the name of the internal service in CONSTANT_CASE
    3. Consider changing the generic values by prefixing them for you project.
       e.g.: NETWORK_NAME=net --> NETWORK_NAME=tool-net
    4. Sadly I did not yet solve the issue with cross-project linking.
       The current workaround required to set the ${SERVICE_NAME}_LOCAL_PATH like the following example
       TOOL_API_LOCAL_PATH=../../tool/tool-api
    5. For each service that that provides an API you should also configure ${SERVICE_NAME}_PORT and ${SERVICE_NAME}_EXTERNAL_PORT Where ${SERVICE_NAME}_PORT defines the port your services will listen too and ${SERVICE_NAME}_EXTERNAL_PORT the port how you want to access the service from your host
11. Run setup of your project

    ./bin/run.js setup

12. Configure the proxy to do HTTPS deconstruction for you services
    Add to config/Caddyfile for each HTTP service a config. Example:

    {$HOST}:{$TOOL_API_EXTERNAL_PORT} {
      tls /config/{$SSL_CERT_PREFIX}-local.crt /config/{$SSL_CERT_PREFIX}-local.key
      reverse_proxy {
        to http://tool-api:{$TOOL_API_PORT}
      }
    }

13. Configure the proxy service to allow your host to access these external ports by extending the ports section of the docker-compose.yml proxy service

    services:
      proxy:
        [...]
        ports:
        - $TOOL_API_EXTERNAL_PORT:$TOOL_API_EXTERNAL_PORT
        [...]

14. Now you can run help to see all your actions

    tCtrl help