Long Demo

In this demo (~15 minutes), we will set up a runing James demo using a prepared Docker image. We will then test the server by connecting with an email client. Finally, we will connect to the server via the REST-based Admin API.

Requirements:

  • Docker

  • curl

  • Thunderbird client (optional)

Set up the demo server

Before starting the server, because we will be connecting to the Admin API we need to set some configuration parameters. We will create a webadmin.properties file that James will use in order to allow us to connect to the API.

Run this command to create the webadmin.properties file:

printf 'enabled=true\nport=8000\nhost=localhost' >> webadmin.properties

Explanation:

  • enabled=true instructs James to run the Admin API service

  • port=8000 configures the Admin API to be made available via port 8000

  • host=localhost configures the Admin API to respond on localhost

Now run the James demo server using this command:

docker run -d -p "25:25" -p "143:143" -p "127.0.0.1:8000:8000" -v $(pwd)/webadmin.properties:/root/conf/webadmin.properties --name james apache/james:demo-3.6.2q

Explanation:

  • docker run runs the provided image with the given parameters

  • The -d parameter runs the container in "detached" mode

  • -p "25:25" -p "143:143" attaches the image ports to the ports 25 (SMTP) and 143 (IMAP) on the host machine

  • `-p "127.0.0.1:8000:8000" attaches the port 8000 to localhost on the host machine to allow us to connect to the Admin API

  • -v $(pwd)/webadmin.properties:/root/conf/webadmin.properties mounts the webadmin.properties file to configure the Admin API

  • The --name james parameter gives the running container a name to make it easier to manipulate

  • linagora/james-jpa-sample:3.4.0 is the image that is used for this demo

Docker will pull the image and start the container.

To run commands using the James CLI, you can use the running container via Docker:

docker exec james james-cli <<COMMAND>>

As an example, list all the domains currently in use by James:

docker exec james james-cli listDomains

You should notice that a default domain, james.local, has been created

List all the current users:

docker exec james james-cli listUsers

You should see users user01@james.local, user02@james.local, and user03@james.local.

Create a new "test.local" domain:

docker exec james james-cli addDomain test.local

List the domains again to ensure that "test.local" has successfully been added:

docker exec james james-cli listDomains

Add the user "testuser" to the "test.local" domain with password "password":

docker exec james james-cli addUser testuser@test.local password

You should now see your newly created user:

docker exec james james-cli listUsers

Connect to the server with an email client

For this demo, we will use Thunderbird, as it is available in multiple languages on Windows, Mac, and Linux.

Go to https://www.thunderbird.net to download Thunderbird.

After you have installed Thunderbird, manually set up an account for user01@james.local using the following parameters:

  • Account name: user01

  • Your name: User 01

  • Email address: user01@james.local

  • SMTP server name: localhost

  • SMTP port: 25

  • SMTP connection security: none

  • SMTP authentication: password

  • IMAP server name: localhost

  • IMAP user name: user01@james.local

  • IMAP port: 143

  • IMAP connection security: none

  • IMAP authentication: none

Repeat the above for testuser@test.local:

  • Account name: testuser

  • Your name: Test User

  • Email address: testuser@test.local

  • SMTP server name: localhost

  • SMTP port: 25

  • SMTP connection security: none

  • SMTP authentication: password

  • IMAP server name: localhost

  • IMAP user name: testuser@test.local

  • IMAP port: 143

  • IMAP connection security: none

  • IMAP authentication: none

Now have fun sending emails back and forth to yourself. :-) But don’t spend all day doing this. You have too much work to do.

Connect to the server via the Admin API

We will use curl to connect to localhost on port 8000, as the Admin API is made available on this port.

List the available domains:

curl http://localhost:8000/domains

You should see a response similar to this:

[
  "edfce41c55e6",
  "james.linagora.com",
  "james.local",
  "localhost",
  "test.local",
  "172.17.0.2"
]

Test that a domain exists:

curl -I -X GET http://localhost:8000/domains/test.local

You should see an empty 204 response, which means "yes, this domain does exist".

Delete our test domain:

curl -X DELETE http://localhost:8000/domains/test.local

Now retest test.local:

curl -I -X GET http://localhost:8000/domains/test.local

This time you will receive a 404 code because the test.local domain no longer exists.

Documentation for the webadmin is available at: http://james.apache.org/server/manage-webadmin.html

Optional

  • Connect manually with SMTP (~5 minutes)

  • Connect manually with POP (~5 minutes)

  • Connect manually with IMAP (~5 minutes)

Stop the demo

To shutdown the server:

docker stop james ; docker rm james

That’s all, folks!