Package and deploy

After testing, you are ready to package your application and deploy to Akka Serverless. The following steps show you how to deploy using the Akka Serverless Console or the CLI.

I. Create a Docker container

  1. Create a .dockerignore file in the shoppingcart directory.

  2. Add the following lines to the .dockerignore file to make sure the docker daemon will not copy these to your container

  3. Create a Dockerfile with the following content:

    # This Dockerfile uses multi-stage build process.
    # See
    # Stage 1: Downloading dependencies and building the application
    FROM node:12.18.0-buster AS builder
    # Set the working directory
    WORKDIR /home/node
    # Install app dependencies
    COPY package*.json ./
    RUN npm ci
    # Copy sources and build the app
    COPY . .
    RUN npm run build
    # Remove dev packages
    # (the rest will be copied to the production image at stage 2)
    RUN npm prune --production
    # Stage 2: Building the production image
    FROM node:12.18.0-buster-slim
    # Set the working directory
    WORKDIR /home/node
    # Copy dependencies
    COPY --from=builder --chown=node /home/node/node_modules node_modules/
    # Copy the app
    COPY --from=builder --chown=node \
      /home/node/package*.json \
      /home/node/*.js \
      /home/node/*.proto \
      /home/node/user-function.desc \
    # Run the app as an unprivileged user for extra security.
    USER node
    # Run
    EXPOSE 8080
    CMD ["npm", "start"]
    This Dockerfile will execute a two-step build, minimizing the size of the container that needs to be pushed to your Docker registry.
  4. Build a new docker container, by running the following command:

    docker build . -t <your docker username>/shoppingcart:tutorial
  5. Push your Docker container to your Docker registry

    docker push <your docker username>/shoppingcart:tutorial

II. Deploy your service

Follow these steps to deploy your container image:

  1. Log in to Akka Serverless:

    1. Sign in to your Akka Serverless account at:

      The Projects page opens.

    2. Click the Add Project card.

    3. In the Project name field, enter ShoppingCart.

    4. Click Create Project.

      Your project should appear in the Projects list. An Akka Serverless administrator will need to activate the project before you can use it.

    1. Log into your account:

      akkasls auth login

      The Login page launches in a browser.

    2. Enter your credentials.

      An authorization page displays.

    3. Click Authorize

    4. In the CLI, create a project to deploy the ShoppingCart service:

      akkasls project new ShoppingCart
    5. Set the project to be your current project:

      akkasls config set project ShoppingCart

      An Akka Serverless administrator will need to activate the project before you can use it.

  2. Deploy your service to Akka Serverless and expose an HTTP route:

    1. In the Services pane, click +.

    2. Enter shoppingcart and click Next.

    3. Enter the path to your container image, which will be something like:

      <registry url>/<registry username>/shoppingcart:tutorial

    4. Click Next.

    5. Skip adding environment variables and click Next.

    6. Move the sliders to add a route and enable CORS, click Next.

    7. Click Finish.

      The Service: shoppingcart card will display Status Ready when your service can accept requests.

    8. From the Routes pane, select and copy the Hostname, you will use it in the next step.

    1. Use the service deploy command to deploy your service:

      akkasls service deploy shoppingcart <your docker registry>/<your docker username>/shoppingcart:tutorial
    2. Validate that your service is Ready

      akkasls service list

      You should see something like the following with a Ready status:

      NAME            AGE     REPLICAS   STATUS             DESCRIPTION
      shoppingcart    60s     1          Ready
    3. Expose the shoppingcart service, with CORS header support to allow connections across domains, with the following command:

      akkasls service expose shoppingcart --enable-cors

      You should see something like the following:

      Service 'shoppingcart' was successfully exposed at:
    4. Copy the hostname to use later. In this example,

III. Test the service

Lightbend hosts a Bend Light Eyeware Web page for this example. You can use it to test your service.

  1. In a new browser tab or window, navigate to the web UI hosted by Lightbend: new tab.

  2. When prompted, enter the route that you copied from the previous step and click Connect.

  3. Enter a user name for your cart.

  4. When you’ve added a few items to your cart, open a new terminal window to use cURL to see the contents of your cart. Be sure to end the request with the user name for your cart:

    curl --request GET --url https://<URL from step 1>.com/com.example.shoppingcart.ShoppingCart/carts/<your user name>

    You should see something like the following:

    {"items":[{"productId":"sg-2","name":"Shield Sunglass","quantity":1},
    {"productId":"sg-4","name":"Pilot Sunglass","quantity":1},
    {"productId":"sg-1","name":"Sonar Sunglass","quantity":1}]}

IV. Verify that the service is stateful

Akka Serverless manages the state for the shoppingcart service, persisting it and retrieving it when requested. When logged into the Bend Light Eyeware UI as described in the previous section, test this yourself:

  1. Add items to your cart.

  2. Click the cart to view the items you added.

  3. Close the browser tab.

  4. Open a new tab with the shopping cart URL: new tab and connect using your hostname, and the same user name you used before.

  5. Click the shopping cart.

All items that you added before closing the browser should still be there, showing that the service is stateful!

What you’ve learned

Congratulations! You’ve implemented a service and deployed it to Akka Serverless. In this tutorial you’ve learned:

  • How to create a new Node.js project with the dependencies for your Akka Serverless project

  • How to create a .proto file and what needs to be in it

  • How to implement the service from the .proto file in your code

  • How to create unit tests to validate your implementation

  • How to build a container and deploy it to Akka Serverless

  • How to expose your service over HTTP and test it