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 linagora/james-jpa-sample:3.4.0
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.
As an example, list all the domains currently in use by James:
./james listDomains
You should notice that a default domain, james.local, has been created
List all the current users:
./james listUsers
You should see users user01@james.local
, user02@james.local
, and user03@james.local
.
Create a new "test.local" domain:
./james addDomain test.local
List the domains again to ensure that "test.local" has successfully been added:
./james listDomains
Add the user "testuser" to the "test.local" domain with password "password":
./james addUser testuser@test.local password
You should now see your newly created user:
./james listUsers
Connect to the server with an email client
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