= Long Demo

In this demo (~15 minutes), we will set up a running 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:

[source,bash]
----
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:

[source,bash]
----
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-latest
----

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
 * `apache/james:demo-latest` 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:

[source,bash]
----
docker exec james james-cli listDomains
----

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

List all the current users:

[source,bash]
----
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:

[source,bash]
----
docker exec james james-cli addDomain test.local
----

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

[source,bash]
----
docker exec james james-cli listDomains
----

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

[source,bash]
----
docker exec james james-cli addUser testuser@test.local password
----

You should now see your newly created user:

[source,bash]
----
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,
https://support.mozilla.org/en-US/kb/manual-account-configuration[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:

[source,bash]
----
curl http://localhost:8000/domains
----

You should see a response similar to this:

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

Test that a domain exists:

[source,bash]
----
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:

[source,bash]
----
curl -X DELETE http://localhost:8000/domains/test.local
----

Now retest `test.local`:

[source,bash]
----
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:

[source]
----
docker stop james ; docker rm james
----

That's all, folks!

