Package and deploy

After testing, the application is ready to package and deploy to Akka Serverless. Use the following steps to deploy using the Akka Serverless Console or the CLI.

1. Create a Docker container

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

  2. Open the .dockerignore file for editing and add following lines to make sure the docker daemon does not copy the added files to the Docker container.

  3. Create a Dockerfile in the shoppingcart directory.

  4. Open the Dockerfile for editing and add 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 executes a two-step build, minimizing the size of the container that needs to be pushed to your Docker registry.
  5. Build a new docker container, by running the following command:

    docker build . -t <your docker username>/shoppingcart:tutorial
    Replace <your docker username> with your Docker user name.
  6. Push your Docker container to your Docker registry

    docker push <your docker username>/shoppingcart:tutorial
    Replace <your docker username> with your Docker user name.

2. Deploy the service

Follow these steps to deploy the 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.

      The shoppingcart project should appear in the Projects list.

    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
  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 the container image, similar to`<registry url>/<registry username>/shoppingcart:tutorial`, and click Next.

    4. Skip adding environment variables and click Next.

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

    6. Click Finish.

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

    7. From the Routes pane, select and copy the Hostname, to use it in the next step.

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

      akkasls service deploy shoppingcart <your docker registry>/<your docker username>/shoppingcart:tutorial


    2. Validate the readiness of the service:

      akkasls service list

      The command returns 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,

The <registry url> for the akkasls services deploy command is optional if you’re using Docker Hub for your container images.

3. Test the service

Lightbend hosts a Bend Light Eyeware Web page for this example. Use this example front-end to test the 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 copied from the previous step and click Connect.

  3. Enter a user name for for the cart.

  4. Add a few items to the cart. The

  5. Open a new terminal window and use cURL to see the contents of the cart:

    End the request with the cart user name.
    curl --request GET --url https://<URL from step 1>.com/carts/<your user name>

    The reqeust returns the items in the cart.

    {"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}]}

4. Verify that the service is stateful

Akka Serverless manages the state for the shoppingcart service, persisting it and retrieving it when requested. Use the following steps to confirm this:

  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.

  5. Click the shopping cart.

All items that 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 and use .proto files for the internal and external interface messaging of an Akka Serverless service.

  • How to create unit tests to validate the service implementation

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

  • How to expose and test a service over HTTP