Task:
Upgrade/replace containerized Sametime 12.0.3 installation w/Ubuntu Podman host (VM) with Sametime 12.0.4
Important Notes:
- We kept the same Mongo database
- We copied the .env, custom.env, and docker-compose.yml to the new folder for reference pending a .old to each filename.
- We kept the same DNS and IP as the previous HCL Sametime server to limit any reconfiguration.
- YAML files are VERY picking about indents. Do NOT use tabs, and make sure your indentions are correct for the configuration options.
- The mongo CLI program is mongosh. Its commands are JSON and do not need a trailing semi-colon.
- For the LDAP account, use a comma and not a slash if using canonical name, alternately, use the email address of the LDAP account instead. If using an email it requires a # before the @ symbol.
Other Upgrade Considerations:
- Since this installation is not in K8s, or RH OCP, we don't have to worry about the ingress switch.
- If you are performing a new installation, use the Mindwatering Support Site HCL Sametime 12.0.2 upgrade notes for the OS and Mongo setup/installations.
Servers:
VM:
sametime.mindwatering.net
192.168.99.107
Primary HCL Domino server for LDAP:
MWDom1/MWDomain
mwdom01.mindwatering.net
192.168.91.101
- port: 636 (389 redirects to 636)
- user: LDAP ServiceID/O=MWDomain
- ST admin email: stadminemailaccount@mindwatering.net
Install HCL Sametime 12.0.4 on Host/VM:
1. Transfer the file to the server:
Using scp or Filezilla from remote machine transfer the install zip to the folder.
You can use /opt/sametime, but in our case we do it by version of software in the myadminid's home folder
- folder: /home/myadminid/st1204/
- Sametime_12.0.4.zip
$ mkdir /home/myadminid/st1204/
- Transfer the file via SCP or Filezilla to inside this new folder.
- The unzip command uses the current folder and does not create a subfolder
$ cd /home/myadminid/st1204
$ unzip Sametime_12.0.4.zip
<wait>
2. Run the install.
Notes:
- For us the install does not completely work. The bind credentials were not in the custom.env afterwards, we had to perform some manual edits.
- If you run another version of Sametime (a FP), this causes us issues with the images, we make sure to shutdown the other ST instance and remove all images (podman rmi) before running install.sh
- Use comma as canonical name separator, or email address for LDAP user.
$ sudo su -
# ./install.sh
<wait while all the images are set-up>
<answer the questions>
- Sametime server name: sametime.mindwatering.net
- Mongo host: 192.168.99.107
- Mongo port: [27017]
<take the default>
- Administrator's user name: sametimeUser
- Password: reallygreatpassword
- Connection URL: [mongodb://sametimeUser:************%23@192.168.99.107:27017]
<take the default>
- LDAP server: mwdom01.mindwatering.net
- LDAP port: 636
- Bind name: cn=ldap serviceid,O=mwdomain
- Base password: **********
- Base DN: o=mwdomain
- TLS access: 636
- displayName: [cn]
<take the default>
- JWT Secret: []
<take the empty default unless you have JWT>
- LTPA: [N]
<take the default>
- Administrator email: stadminemailaccount@mindwatering.net
- Grafana Admin user: admin
<take the default>
- Grafana Password: MyGreatGrafanaPassword
- Initiate and wait
IMPORTANT:
- The first run will fail because the bind information is not actually saved.
- The first run will create empty folders as files, and not setup the sametime-config folder if permissions are not correct first. The installation warns to make sure the permissions are correct on the sametime-config folder. Documentation does not include details on this; however, HCL support was kind enough to elaborate. See that info in the troubleshooting section below.
3. Fix the install and perform pre-run tweaks:
a. If you already started Sametime accidentally, stop it:
$ sudo podman-compose down -t100
<wait and confirm no folders/files in the sametime-config folder>
b. Fix sametime-config folder permissions
# cd /home/myadminid/st1204/
# chmod -R u+rw sametime-config
# chmod -R g+rw sametime-config
c. Fix the LDAP bind in the config custom.env file:
$ sudo vi /home/myadminid/st1204/custom.env
. . .
# LDAP configuration
. . .
LDAP_BIND_ENTRY_DN_ENV=cn=ldap serviceid,o=mwdomain
LDAP_BIND_ENTRY_PWD_ENV= **********
LDAP_PERSON_RESOLVE_BASE_ENV=o=mwdomain
. . .
ENABLE_GRAFANA_PROXY=true
MONITORING_ENABLED=true
. . .
<esc>:wq (to save)
d. Verify the admin user and its password are in the Grafana monitoring.env file:
$ sudo vi /home/myadminid/st1204/monitoring.env
. . .
GF_SECURITY_ADMIN_USER=admin
GF_SECURITY_ADMIN_PASSWORD=MyGreatGrafanaPassword
. . .
<esc>:wq (to save)
e. Verify the config .env file monitoring:
$ sudo vi /home/myadminid/st1204/.env
. . .
COMPOSE_PROFILES=monitoring
. . .
<esc>:wq (to save)
f. Replace the Prometheus config with the bundled Sametime one (in the extracted zip):
- Check/replace the /home/myadminid/st1204/prometheus.yml config file:
Notes:
- If using the chat only version, the file name will be prometheus-limited.yml
- If, when podman-compose up -d is run, and the prometheus gives error that we are mounting directory as a file. The simplest solution is to put the prometheus.yml file in its own folder, and update the docker-compose.yml file, prometheus container, and volumes section. (2026/11/06 MW TB addition)
- Create the prometheus folder and move the prometheus.yml file:
$ mkdir /home/myadminid/st1204/prometheus/
$ mv /home/myadminid/st1204/prometheus.yml /home/myadminid/st1204/prometheus/
- Update the docker-compose.yml file:
- - update the line below:
- ./prometheus-limited.yml:/etc/prometheus/prometheus.yml
or
- ./prometheus.yml:/etc/prometheus/prometheus.yml
$ vi /home/myadminid/st1204/docker-compose.yml
...
./prometheus:/etc/prometheus
...
<esc>:wq (to save)
g. To put off LetsEncrypt setup until after the first run:
Note:
- This will instruct Sametime to create a self-certificate until we enable it
$ vi /home/myadminid/st1204/custom.env
...
#ENABLE_LETSENCRYPT=1
LETSENCRYPT_DOMAIN=sametime.mindwatering.com
LETSENCRYPT_EMAIL=acmeemailaccount@mindwatering.net
#LETSENCRYPT_USE_STAGING=1
...
<esc>:wq (to save)
h. If you changed anything in docker-compose.yml, validate the syntax:
Note:
- This will not fix a runtime evaluation issue.
$ python3 -c "import yaml; list(yaml.safe_load_all(open('docker-compose.yml')))"
4. Run Sametime for first time:
a. Start Sametime:
$ sudo docker-compose up -d
<wait - confirm all the returned status values are a 0>
b. Verify containers and logs:
Important:
- If any containers have a status other than "exit status 0", troubleshoot the container and view its logs.
- See troubleshoot tips at the end of this document.
- Check container status:
$ podman ps -a
<check the Status column - except for the st1204_proxy-init_1 container, they should say Up for ...>
- Check ngix ports:
$ sudo podman port st1204_nginx_1
8080/tcp -> 0.0.0.0:80
4443/tcp -> 0.0.0.0:443
- Check chat login in web browser:
web browser --> sametime.mindwatering.net
<confirm loads after accepting self-certificate warnings>
Note:
- If all is not well start troubleshooting nginx_1 and proxy_1
- Check Grafana monitoring interface:
web browser --> sametime.mindwatering.net:3001
<site is http, rather than https, confirm shows login screen>
Note:
- If all is not well start troubleshooting grafana_1 and proxy_1
5. If all is well, apply the pre-LetsEncrypt configuration fix:
6. Update the config files to enable LetsEncrypt:
Post-Install:
1. Create a one-off Service for the Sametime containers to auto-start:
$ cd /usr/lib/systemd/system/
$ sudo touch podman-compose-app.service
$ vi podman-compose-app.service
[Unit]
Description=Podman Compose Application Service
Requires=podman.service
After=podman.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/myadminid/st1204
ExecStart=/usr/bin/podman-compose up -d
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
<esc>:wq (to save)
Enable the service:
$ sudo systemctl enable podman-compose-app.service
Troubleshooting and Misc Podman Commands w/ Sametime:
LDAP Failure from Sametime to Domino LDAP directory:
LDAP entry with / causing bind to fail: mwdom01.mindwatering.net. [48] Inappropriate authentication
- KB0116572
- Start-up error:
sed: -e expression #1, char 70: unknown option to `s'
- Authentication log error:
stusers 2024-11-20 20:39:26.873 INFO 113 --- 123399941506880 : StLdapConnection::bind: dn = (null)
stusers 2024-11-20 20:39:26.873 INFO 113 --- 123399941506880 : StLdapConnection::asyncBind: dn = (null)
stusers 2024-11-20 20:39:27.013 INFO 113 --- 123399941506880 : StLdapConnection::asyncResult: m_pConn = 0x703b2c78e6a0 msgId = 1 timeLimit = 0
stusers 2024-11-20 20:39:27.015 INFO 113 --- 123399941506880 : Failed connecting to directory server mwdom01.mindwatering.net. [48] Inappropriate authentication
This error is caused by the name added w/Notes canonical format instead of email address or using comma as delineator:
LDAP_BIND_ENTRY_DN_ENV=cn=ldap accountname,o=mindwateringdomain
or
LDAP_BIND_ENTRY_DN_ENV=cn=accountname@mindwatering.net
Mongo BIND URL Failure:
Error Message:
...
INFO 1 --- [ering.com:27017] org.mongodb.driver.cluster : Exception in monitor thread while connecting to server tribe.mindwatering.com:27017
com.mongodb.MongoSocketOpenException: Exception opening socket
at com.mongodb.internal.connection.SocketStream.lambda$open$0(SocketStream.java:85) ~[mongodb-driver-core-5.5.2.jar:na]
at java.base/java.util.Optional.orElseThrow(Unknown Source) ~[na:na]
at com.mongodb.internal.connection.SocketStream.open(SocketStream.java:85) ~[mongodb-driver-core-5.5.2.jar:na]
at com.mongodb.internal.connection.InternalStreamConnection.open(InternalStreamConnection.java:233) ~[mongodb-driver-core-5.5.2.jar:na]
at com.mongodb.internal.connection.DefaultServerMonitor$ServerMonitor.lookupServerDescription(DefaultServerMonitor.java:219) ~[mongodb-driver-core-5.5.2.jar:na]
at com.mongodb.internal.connection.DefaultServerMonitor$ServerMonitor.run(DefaultServerMonitor.java:176) ~[mongodb-driver-core-5.5.2.jar:na]
Caused by: java.net.ConnectException: Connection refused
...
Possible Cause:
- Install.sh messed up and left out the # (%23) required if using an email address:
$ sudo vi /home/myadminid/st1204/custom.env
...
# Mongo DB connection URL
MONGO_URL=mongodb://sametimeUseName:MyReallyGoodPassword4This%23@sametime.mindwatering.net:27017
...
<esc>:wq (to save)
HCL Support response on sametime-config folder permissions for first podman compose startup:
Regarding sametime-config Permissions:
Looking at your ls -l line:
drwxrwx--x 7 sysadmin sysadmin 4096 sametime-config
Your sysadmin group is GID 1000. In the proxy log you shared earlier: CONTAINER USER uid:1002 gid:[1000] - PATH:/workspace/proxy-storage owner:1002 group:1000
The backend services run under non-root service accounts that share GID 1000. This explains why giving g+rw works reliably in your environment: the containers write to that directory via group ownership. Your current 770 or 771 permission with myadminid:myadminid ownership is completely sound for a rootful Podman setup on Ubuntu.
First Run Validation check Nginx container ports:
$ sudo podman port st1204_nginx_1
8080/tcp -> 0.0.0.0:80
4443/tcp -> 0.0.0.0:443
$ ss -tlpn | grep -E ':(80|443)\b'
LISTEN 0 4096 0.0.0.0:80 0.0.0.0:* users:(("conmon",pid=2660230,fd=5))
LISTEN 0 4096 0.0.0.0:443 0.0.0.0:* users:(("conmon",pid=2660230,fd=6))
$ sudo podman exec st1204_nginx_1 ss -tlpn
State Recv-Q Send-Q Local Address:Port Peer Address:PortProcess
LISTEN 0 511 0.0.0.0:4443 0.0.0.0:* users:(("nginx",pid=709,fd=7),("nginx",pid=708,fd=7),("nginx",pid=707,fd=7),("nginx",pid=706,fd=7),("nginx",pid=694,fd=7))
LISTEN 0 511 0.0.0.0:8080 0.0.0.0:* users:(("nginx",pid=709,fd=5),("nginx",pid=708,fd=5),("nginx",pid=707,fd=5),("nginx",pid=706,fd=5),("nginx",pid=694,fd=5))
LISTEN 0 511 [::]:4443 [::]:* users:(("nginx",pid=709,fd=8),("nginx",pid=708,fd=8),("nginx",pid=707,fd=8),("nginx",pid=706,fd=8),("nginx",pid=694,fd=8))
LISTEN 0 511 [::]:8080 [::]:* users:(("nginx",pid=709,fd=6),("nginx",pid=708,fd=6),("nginx",pid=707,fd=6),("nginx",pid=706,fd=6),("nginx",pid=694,fd=6))
$ sudo podman logs nginx_1
<view results, ensure it is not crash looping>
Confirming Container Repo/Registries:
$ grep -v '^#' /etc/containers/registries.conf | grep -v '^$' and ls -la /etc/containers/registries.conf.d/
<view output>
Important:
- If you don't have any returned, ensure you update the docker-compose.yml containers to use fully qualified paths.
e.g.
$ vi /home/myadminid/st1204/docker-compose.yml
...
prometheus:
image: docker.io/prom/prometheus:latest
...
node-exporter:
image: docker.io/prom/node-exporter
...
grafana:
image: docker.io/grafana/grafana:latest
...
<esc>:wq (to save)
Troubleshooting Grafana:
- Output internal port (3000) proxy config:
$ grep -n -B3 -A8 grafana sametime-config/web/nginx/chat.conf
319-
320-
321-
322:location /grafana/ {
323: rewrite ^/grafana/(.*) /$1 break;
324- proxy_set_header Host $http_host;
325- proxy_hide_header X-Frame-Options;
326: proxy_pass http://grafana:3000;
327-}
328-
329-# Proxy Grafana Live WebSocket connections.
330:location /grafana/api/live/ {
331: rewrite ^/grafana/(.*) /$1 break;
332- proxy_http_version 1.1;
333- proxy_set_header Upgrade $http_upgrade;
334- proxy_set_header Connection $connection_upgrade;
335- proxy_set_header Host $http_host;
336- proxy_hide_header X-Frame-Options;
337: proxy_pass http://grafana:3000;
338-}
339-
340-
Container podman and podman-compose Commands:
podman ps
- view podman containers loaded/running
podman container list -a
- another command to view podman containers loaded/running
podman-compose up -d
- startup containers for the current Sametime folder
podman-compose down -t 60
- shutdown containers for the current Sametime folder, and give 60 seconds for each container instead of the default 10 seconds before the send kill command being issued
podman-compose logs
- view logs from all the containers from the pod for this Sametime folder
podman-compose logs community
- view logs just from the community container
podman-compose logs nginx
- view logs just from the nginx web server
podman rm -a
- issue only after the down command above, to remove all containers
podman image rm -a
- issue only after the down command, and if no containers are loaded, removes the images that the ./install.sh set-up
podman rmi --all
- issue only after the down command, removes all images from the local image repository.
- effectively uninstalls sametime and any other images from host
podman exec -it foldername_community_1 bash
- start bash terminal session into the community container
- Note: vi is not available, but cat is available, and downloading a file is an option, as well
podman exec -it foldername_grafana_1 /bin/sh
- start sh terminal session into the Grafana container (BASH isn't available)
podman exec -it foldername_prometheus_1 /bin/sh
- start sh terminal session into the Grafana container (BASH isn't available)
podman cp foldername_community_1 :/sametime.ini ../tmp/sametime.ini
- copies the sametime.ini from the container to the host, up one folder and down into another tmp folder for transfer for analysis
podman cp ../tmp/sametime.ini foldername_community_1:/sametime.ini
- copies the edited file with the new debug, for example, back up to the sametime community container, overwriting the currently used on in the container.
podman-compose logs --since 10m
- all of the pod container logs, but only the last 10 minutes of them
New Sametime client VPS codes:
HCL Notes 12.0.2 64-bit: 122c --> Add to VPS_ALLOWED_LOGIN_TYPES in sametime.ini
- See the table of codes: KB0024444
Per HCL Support, add to custom.env:
$ cd/home/myadminid/st1204
. . .
STI__config__VPS_ALLOWED_LOGIN_TYPES=129D,129C,129B,129A,122c,130F,130E,130D,130C,130B,130A,1308,1306,1304,1443,143C,143D,143E,143F,143A,1439,1438,1437,143B,1436,1435,1434,14AF,14B2,14B4,14B6,14AD,14A2,14A0
. . .
<esc>:wq (to save)
previous page
|