|
| 1 | +# Configuration |
| 2 | + |
| 3 | +PhotoMapAI is primarily configured through the web interface as described in [Basic Usage](user-guide/basic-usage.md#changing-settings) and [Albums](user-guide/albums.md). However, there are a number of runtime parameters that control how the web service behaves. |
| 4 | + |
| 5 | +## Changing the Web Host and Port |
| 6 | + |
| 7 | +By default, PhotoMapAI runs its web service on port 8050 and only accepts connections on the local machine (`localhost`). These can be changed on the command line used to launch the application using the `--port` and `--host` options: |
| 8 | + |
| 9 | + start_photomap --port 8000 --host 0.0.0.0 |
| 10 | + |
| 11 | +This command changes the port to port 8000, and allows PhotoMapAI to listen for connections on the wildcard IP address `0.0.0.0`, meaning that it will accept connections for any network-accessible location. |
| 12 | + |
| 13 | +If you are using a launcher script to start PhotoMapAI (e.g. `start_photomap.bat`) you can change these values by opening the script in a text editor (`Notepad` on Windows), finding the line containing `start_photomap`, and adding the options as shown above. |
| 14 | + |
| 15 | +Alternatively, you can change the port and host interface by setting two environment variables prior to launching PhotoMapAI. These are: |
| 16 | + |
| 17 | +* `PHOTOMAP_HOST` - the host interface to accept connections from |
| 18 | +* `PHOTOMAP_PORT` - the listen port |
| 19 | + |
| 20 | +On Linux and Macintosh systems, you can set these environment variables on the command line like so: |
| 21 | + |
| 22 | +```bash |
| 23 | +PHOTOMAP_HOST="0.0.0.0" PHOTOMAP_PORT="8000" start_photomap |
| 24 | +``` |
| 25 | + |
| 26 | +Or you can permanently fix these environment variables by setting them in your shell's profile, e.g. `.bashrc`. |
| 27 | + |
| 28 | +On Windows systems, setting environment variables can be done through the GUI as well as on the command line. See [How to Set Environment Variables in Windows](https://phoenixnap.com/kb/windows-set-environment-variable) for a good walkthrough. |
| 29 | + |
| 30 | +## Running PhotoMapAI Under HTTPS |
| 31 | + |
| 32 | +By default, PhotoMapAI runs as a non-secure `HTTP` service. This generates a warning icon in some browsers, but more seriously prevents cut and paste between the PhotoMapAI tab and browser tabs and desktop applications. |
| 33 | + |
| 34 | +There are several ways to enable HTTP for PhotoMapAI: |
| 35 | + |
| 36 | +### Install a Self-Signed SSL Certificate |
| 37 | + |
| 38 | +In this method, you generate self-signed encryption certificate and |
| 39 | +private key files and point PhotoMapAI to them using its `--cert` and |
| 40 | +`--key` command-line options. |
| 41 | + |
| 42 | +Guides to generating and installing self-signed certificates: |
| 43 | + |
| 44 | +- [Creating Self-Signed Certificates with Windows PowerShell](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate). Please apply the arguments to create .crt and .pem files. |
| 45 | + |
| 46 | +- [Creating Self-Signed Certificates with OpenSSL (Mac/Linux)](https://gist.github.com/elklein96/a15090f35a41e16bdc8574a7fb81e119) |
| 47 | + |
| 48 | +These methods will leave you with two files, a .crt certificate file, |
| 49 | +and a .pem key file. Relaunch the PhotoMapAI server using `--cert |
| 50 | +/path/to/.crt file` and `--key /path/to/.pem file`. If you are using |
| 51 | +the desktop launcher to start the server, simply open the launcher |
| 52 | +file with a text editor, and add the `--cert` and `--key` options to |
| 53 | +the end of the line that ends with `start_photomap`. |
| 54 | + |
| 55 | +After installing the certificate/key pair and relaunching the server, |
| 56 | +you will be able to access the PhotoMapAI server using the https:// |
| 57 | +URL. Your browser will complain about an unknown certificate authority |
| 58 | +when you first load the URL and ask you to confirm that you trust the site. |
| 59 | + |
| 60 | +### Use Certbot |
| 61 | + |
| 62 | +The [Certbot](https://certbot.eff.org/) tool provides public certificates that |
| 63 | +browsers automatically trust. It is very easy to use, but it requires that you |
| 64 | +have a web running on port 80 that accepts incoming HTTP connections. |
| 65 | + |
| 66 | +Once the Certbot certificate and keyfile are generated, follow the |
| 67 | +directions in the previous section to configure PhotoMapAI to use them. |
| 68 | + |
| 69 | + |
| 70 | +### Use a Reverse Proxy |
| 71 | + |
| 72 | +A final option is to keep PhotoMapAI running on HTTP, but use a reverse |
| 73 | +proxy from a running web server to translate HTTPS requests on the |
| 74 | +reverse proxy into HTTP requests to PhotoMapAI. The main advantage of this |
| 75 | +is that you get the additional benefit of all the web server's configuration |
| 76 | +controls, such as the ability to add password protection. |
| 77 | + |
| 78 | +Here are some guides for setting up reverse proxies. The first is a |
| 79 | +general guide for configuring a reverse proxy with the popular Nginx |
| 80 | +web server. The second features a Windows-specific walkthrough. |
| 81 | + |
| 82 | +- [NGINX Reverse Proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) |
| 83 | +- [NGINX Reverse Proxy on Windows](https://virendra.dev/blog/setting-up-nginx-as-a-reverse-proxy-on-windows) |
| 84 | + |
| 85 | +You will need to install encryption certificates for the Nginx server using [Certbot](https://certbot.eff.org/). The final configuration of the proxy server will look something like this: |
| 86 | + |
| 87 | + location /photomap/ { |
| 88 | + proxy_pass http://localhost:8050/; |
| 89 | + |
| 90 | +This is saying that when a request comes in for |
| 91 | +`https://your.host/photomap/` it will be translated into a request to |
| 92 | +`http://localhost:8050/` where PhotoMapAI is running. It is possible to |
| 93 | +run the proxy server and the PhotoMapAI server on separate machines as well. |
| 94 | + |
| 95 | +## Pointing to an Alternative Configuration File |
| 96 | + |
| 97 | +PhotoMapAI stores its album definitions and other configuration information in a configuration file. It is not usually necessary to manipulate it directly, but if you wish you can point to an alternative config file in order to have multiple PhotoMapAI servers each hosting separate album collections. |
| 98 | + |
| 99 | +The config file is stored in different places depending on the platform: |
| 100 | + |
| 101 | +| Platform | Config File Path | |
| 102 | +|------------------|-------------------------| |
| 103 | +| Linux | ~/.config/photomap/config.yaml | |
| 104 | +| MacOS | ~/Library/Application Support/photomap/config.yaml | |
| 105 | +| Windows | C:\Users\<user>\AppData\Roaming\photomap\config.yaml| |
| 106 | + |
| 107 | +To run PhotoMapAI off a different config file, you may launch it with the `--config` option on the command line, similar to setting the port and host. In the below example we specify an alternative config file named `photomap_2.yaml` |
| 108 | + |
| 109 | + start_photomap --config ~/photomap_2.yaml |
| 110 | + |
| 111 | +If the indicated config file doesn't exist when you launch PhotoMapAI, it will be created automatically. |
| 112 | + |
| 113 | +You may also point to an alternative configuration file by setting the environment variable `PHOTOMAP_CONFIG`, as described in the previous section: |
| 114 | + |
| 115 | +```bash |
| 116 | +PHOTOMAP_CONFIG=~/photomap_2.yaml start_photomap |
| 117 | +``` |
| 118 | + |
| 119 | +It is also possible, but not recommended, to edit the configuration file directly using a text editor. The format is straightforward to understand, but liable to change in the future. |
0 commit comments