Setting up Gateway in Multitenant Windows Environments

The standard Gateway setup/install is done under the assumption that the user who is creating the agent and plugins will be the sole user responsible for maintaining them. However, in some cases there might be a need for setting up Gateway on a server that is accessed by multiple individuals who made need to access and change agent/plugin configurations.

Information used by the agent to determine what plugins and what plugin configurations are accessible are stored in a data directory. By default, during installation (using the install.bat file in the windows directory of the zip file that is downloaded from the Data & Insights platform), the data directory will be mapped to the user’s “%LOCALAPPDATA%\socrata-ingress-agent” directory. This usually expands to something like “C:\Users\<user>\AppData\Local\socrata-ingress-agent\”

This is fine for instances where a single user is going to manage the agent, however, it becomes problematic when multiple users need to be able to configure the agent/plugins.

Note: For existing agents, copy the folder mentioned previously (ex: “C:\Users\<user>\AppData\Local\socrata-ingress-agent\”) to the new desired directory. Then, follow the steps below to update the agent to look at this new filepath.

Setup

There are a few ways to update this, but the easiest is to edit the install.bat file and change the lines stating:

--StartParams "--data-dir";"%LOCALAPPDATA%\socrata-ingress-agent" ^

to read:

--StartParams "--data-dir";"[YOUR DESIRED PATH]\socrata-ingress-agent" ^

*Note: you do not have to specify "socrata-ingress-agent" However, it may be clearer to include it.

After running, or re-running for existing agent setups, the install.bat file as an administrator, the agent will now default to looking in the specified path.

Configuring Plugins

Now that the agent is reading from a non-user-specific path, we need to ensure that the plugins are configured to use that path as well. To do that, we need to use the "--data-dir" flag when configuring the plugin, like so:

java -jar socrata-ingress-agent.jar --data-dir "[YOUR DESIRED PATH]\socrata-ingress-agent" --configure-plugin [plugin]:[plugin name]

To make this easier, you can also save this command to a “configure.bat” file in the agent home directory, so that future users will know to use that to configure the plugin, instead of having to remember the exact data directory.

After a configure.bat file is created, you simply need to double click on it to retrieve the plugin configuration.

Migrating Existing Plugins

In some cases, the plugins have already been configured by someone and they need to be made accessible to more users.

In that case, follow these steps:

1. Stop the service if it is running.

2. Navigate to the Gateway directory
3. Navigate to the windows sub directory
4. Open the exe file that corresponds to the service that was created
5. Go to the “Startup” tab
   1. 1. 1. 1. 1. 1. 1. 
6. Grab the data directory path (e.g. C:\Users\USER.NAME\AppData\Local\socrata-ingress-agent Where USER.NAME is the user who installed the agent.
7. You should see an alphanumeric folder in that directory
   • If you see multiple folders, that means that multiple agents are installed - in order to determine which is the correct one, open command prompt and from the Gateway directory run:java -jar socrata-ingress-agent.jar --show-agent-data-dir
     Output: C:\Users\USER.NAME\AppData\Local\socrata-ingress-agent\xWQe05Ee8K-z76_eqjCJjDz0PHb-mSZWVqVoRbx295pI
8. Copy that directory and move it to the desired shared location
9. Edit the install.bat file as noted above
10. Re-run the install.bat file as an admin