feat: add base-path support for running behind reverse proxy (#515)

Add --base-path CLI option and BASE_PATH env variable to allow deploying
behind a reverse proxy (e.g., nginx). All routes use an Express Router
mounted at the base path. All views updated to use basePath for links,
assets, fetch URLs, and breadcrumb navigation. Fix mismatched quotes in
EJS templates and add missing build step in Dockerfile.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: m-pavel

Dockerfile

@@ -10,6 +10,7 @@ COPY rollup.config.ts .
 COPY tsconfig.json .
 
 RUN npm ci
+RUN npm run build
 
 FROM node:20-alpine
 EXPOSE 8001

README.md

@@ -18,9 +18,10 @@ Options:
  - `--port PORT` / `-p PORT` -  Port to run on (default: 8001)
  - `--host HOST` / `-h HOST` -  Host to run on (default: localhost)
  - `--dynamo-endpoint` - DynamoDB endpoint to connect to (default: http://localhost:8000).
+ - `--base-path` - Base path for the application (e.g., /dynamo). Useful when running behind a reverse proxy (default: empty).
  - `--skip-default-credentials` - Skip setting default credentials and region. By default the accessKeyId/secretAccessKey are set to "key" and "secret" and the region is set to "us-east-1". If you specify this argument then you need to ensure that credentials are provided some other way. See https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html for more details on how default credentials provider works.
 
-Environment variables `HOST`, `PORT` and `DYNAMO_ENDPOINT` can also be used to set the respective options.
+Environment variables `HOST`, `PORT`, `BASE_PATH` and `DYNAMO_ENDPOINT` can also be used to set the respective options.
 
 If you use a local dynamodb that cares about credentials, you can configure them by using the following environment variables `AWS_REGION` `AWS_ACCESS_KEY_ID` `AWS_SECRET_ACCESS_KEY` or specify the `--skip-default-credentials` argument and rely on the default AWS SDK credentials resolving behavior.
 
@@ -33,6 +34,27 @@ If you are accessing your database from another piece of software, the `AWS_ACCE
 
 By default `dynamodb-admin` sets a default key/secret to values "key" and "secret" and the region to "us-east-1".
 
+### Running behind a reverse proxy
+
+When running behind a reverse proxy like nginx, you can use the `--base-path` option to specify a custom base path:
+
+```bash
+dynamodb-admin --base-path=/dynamo
+```
+
+Example nginx configuration:
+
+```nginx
+location /dynamo/ {
+    proxy_pass http://localhost:8001/;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection 'upgrade';
+    proxy_set_header Host $host;
+    proxy_cache_bypass $http_upgrade;
+}
+```
+
 ### Use as a library in your project
 
 This requires AWS SDK v3.

bin/dynamodb-admin.ts

@@ -48,9 +48,15 @@ parser.add_argument('--skip-default-credentials', {
     help: 'Skip setting default credentials and region. By default the accessKeyId/secretAccessKey are set to "key" and "secret" and the region is set to "us-east-1". If you specify this argument then you need to ensure that credentials are provided some other way. See https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html for more details on how default credentials provider works.',
 });
 
-const { host, port, open: openUrl, dynamo_endpoint: dynamoEndpoint, skip_default_credentials: skipDefaultCredentials } = parser.parse_args();
+parser.add_argument('--base-path', {
+    type: 'str',
+    default: process.env.BASE_PATH || '',
+    help: 'Base path for the application (e.g., /dynamo). Useful when running behind a reverse proxy.',
+});
+
+const { host, port, open: openUrl, dynamo_endpoint: dynamoEndpoint, skip_default_credentials: skipDefaultCredentials, base_path: basePath } = parser.parse_args();
 
-const app = createServer({ dynamoEndpoint, skipDefaultCredentials });
+const app = createServer({ dynamoEndpoint, skipDefaultCredentials, basePath });
 const server = app.listen(port, host);
 server.on('listening', () => {
     const address = server.address();

lib/backend.ts

@@ -10,10 +10,11 @@ export type CreateServerOptions = {
     expressInstance?: Express;
     dynamoEndpoint?: string;
     skipDefaultCredentials?: boolean;
+    basePath?: string;
 };
 
 export function createServer(options?: CreateServerOptions): Express {
-    const { dynamoDbClient, expressInstance, dynamoEndpoint, skipDefaultCredentials } = options || {};
+    const { dynamoDbClient, expressInstance, dynamoEndpoint, skipDefaultCredentials, basePath = '' } = options || {};
     const app = expressInstance || express();
     let dynamodb = dynamoDbClient;
 
@@ -27,7 +28,7 @@ export function createServer(options?: CreateServerOptions): Express {
 
     const ddbApi = new DynamoApiController(dynamodb);
 
-    setupRoutes(app, ddbApi);
+    setupRoutes(app, ddbApi, basePath);
 
     return app;
 }

lib/routes.ts

@@ -14,32 +14,35 @@ import type { DynamoApiController } from './dynamoDbApi';
 
 const DEFAULT_THEME = process.env.DEFAULT_THEME || 'light';
 
-export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
-    app.use(errorhandler());
-    app.use('/assets', express.static(path.join(__dirname, '..', 'public')));
+export function setupRoutes(app: Express, ddbApi: DynamoApiController, basePath = ''): void {
+    const router = express.Router();
 
-    app.use(
+    router.use(errorhandler());
+    router.use('/assets', express.static(path.join(__dirname, '..', 'public')));
+
+    router.use(
         cookieParser(),
         (req, res, next) => {
             const { theme = DEFAULT_THEME } = req.cookies;
             res.locals = {
                 theme,
+                basePath,
             };
             next();
         },
     );
 
-    app.get('/', asyncMiddleware(async(_req, res) => {
+    router.get('/', asyncMiddleware(async(_req, res) => {
         const data = await listAllTables(ddbApi);
         res.render('tables', { data });
     }));
 
-    app.get('/api/tables', asyncMiddleware(async(_req, res) => {
+    router.get('/api/tables', asyncMiddleware(async(_req, res) => {
         const data = await listAllTables(ddbApi);
         res.send(data);
     }));
 
-    app.get('/create-table', (_req, res) => {
+    router.get('/create-table', (_req, res) => {
         res.render('create-table', {});
     });
 
@@ -58,7 +61,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         IndexType: 'global' | 'local';
     };
 
-    app.post(
+    router.post(
         '/create-table',
         bodyParser.json({ limit: '500kb' }),
         asyncMiddleware(async(req, res) => {
@@ -170,7 +173,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         }),
     );
 
-    app.delete('/tables', asyncMiddleware(async(_req, res) => {
+    router.delete('/tables', asyncMiddleware(async(_req, res) => {
         const tablesList = await listAllTables(ddbApi);
         if (tablesList.length === 0) {
             res.send('There are no tables to delete');
@@ -180,7 +183,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.send('Tables deleted');
     }));
 
-    app.delete('/tables-purge', asyncMiddleware(async(req, res) => {
+    router.delete('/tables-purge', asyncMiddleware(async(req, res) => {
         const tablesList = await listAllTables(ddbApi);
         if (tablesList.length === 0) {
             res.send('There are no tables to purge');
@@ -190,27 +193,27 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.send('Tables purged');
     }));
 
-    app.delete('/tables/:TableName', asyncMiddleware(async(req, res) => {
+    router.delete('/tables/:TableName', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         await ddbApi.deleteTable({ TableName });
         res.status(204).end();
     }));
 
-    app.delete('/tables/:TableName/all', asyncMiddleware(async(req, res) => {
+    router.delete('/tables/:TableName/all', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         await purgeTable(TableName, ddbApi);
         res.status(200).end();
     }));
 
-    app.get('/tables/:TableName/get', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName/get', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const hash = req.query.hash as string;
         const range = req.query.range as string;
         if (hash) {
             if (range) {
-                res.redirect(`/tables/${encodeURIComponent(TableName)}/items/${encodeURIComponent(hash)},${encodeURIComponent(range)}`);
+                res.redirect(`${basePath}/tables/${encodeURIComponent(TableName)}/items/${encodeURIComponent(hash)},${encodeURIComponent(range)}`);
             } else {
-                res.redirect(`/tables/${encodeURIComponent(TableName)}/items/${encodeURIComponent(hash)}`);
+                res.redirect(`${basePath}/tables/${encodeURIComponent(TableName)}/items/${encodeURIComponent(hash)}`);
             }
             return;
         }
@@ -225,7 +228,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         });
     }));
 
-    app.get('/tables/:TableName', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName', asyncMiddleware(async(req, res) => {
         const TableName = req.params.TableName;
         req.query = pickBy(req.query);
         const pageNum = typeof req.query.pageNum === 'string' ? Number.parseInt(req.query.pageNum) : 1;
@@ -252,7 +255,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.render('scan', data);
     }));
 
-    app.get('/tables/:TableName/items', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName/items', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         req.query = pickBy(req.query);
         const filters = typeof req.query.filters === 'string' ? JSON.parse(req.query.filters) : {};
@@ -352,7 +355,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.json(data);
     }));
 
-    app.get('/tables/:TableName/meta', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName/meta', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const [tableDescription, items] = await Promise.all([
             ddbApi.describeTable({ TableName }),
@@ -365,7 +368,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.render('meta', data);
     }));
 
-    app.delete('/tables/:TableName/items/:key', asyncMiddleware(async(req, res) => {
+    router.delete('/tables/:TableName/items/:key', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const tableDescription = await ddbApi.describeTable({ TableName });
         await ddbApi.deleteItem({
@@ -375,7 +378,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.status(204).end();
     }));
 
-    app.get('/tables/:TableName/add-item', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName/add-item', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const tableDescription = await ddbApi.describeTable({ TableName });
         const Item: Record<string, string | number> = {};
@@ -397,7 +400,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         });
     }));
 
-    app.get('/tables/:TableName/items/:key', asyncMiddleware(async(req, res) => {
+    router.get('/tables/:TableName/items/:key', asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const tableDescription = await ddbApi.describeTable({ TableName });
         const params = {
@@ -418,7 +421,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         });
     }));
 
-    app.put('/tables/:TableName/add-item', bodyParser.json({ limit: '500kb' }), asyncMiddleware(async(req, res) => {
+    router.put('/tables/:TableName/add-item', bodyParser.json({ limit: '500kb' }), asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const tableDescription = await ddbApi.describeTable({ TableName });
         await ddbApi.putItem({ TableName, Item: req.body });
@@ -432,7 +435,7 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         return;
     }));
 
-    app.put('/tables/:TableName/items/:key', bodyParser.json({ limit: '500kb' }), asyncMiddleware(async(req, res) => {
+    router.put('/tables/:TableName/items/:key', bodyParser.json({ limit: '500kb' }), asyncMiddleware(async(req, res) => {
         const { TableName } = req.params;
         const tableDescription = await ddbApi.describeTable({ TableName });
         await ddbApi.putItem({ TableName, Item: req.body });
@@ -443,8 +446,10 @@ export function setupRoutes(app: Express, ddbApi: DynamoApiController): void {
         res.json(response.Item);
     }));
 
-    app.use(((error, _req, res, _next) => {
+    router.use(((error, _req, res, _next) => {
         console.info(error.stack);
         res.status(500).json({ message: error.message });
     }) as ErrorRequestHandler);
+
+    app.use(basePath, router);
 }

views/create-table.ejs

@@ -61,7 +61,7 @@
                     body: JSON.stringify(createTableRequest)
                 })
                 if (response.ok) {
-                    window.location = '/'
+                    window.location = '<%= basePath %>/'
                 } else {
                     const error = await response.text()
                     handleError(JSON.parse(error).message)

views/get.ejs

@@ -10,7 +10,7 @@
     <%
       const breadcrumb = [
         {
-          href: '/',
+          href: basePath + '/',
           text: 'Tables',
         },
         {
@@ -24,17 +24,17 @@
 
     <ul class='nav nav-tabs'>
       <li class='nav-item'>
-        <a class='nav-link' href='/tables/<%= encodeURIComponent(Table.TableName) %>'>
+        <a class='nav-link' href='<%= basePath %>/tables/<%= encodeURIComponent(Table.TableName) %>'>
           Items
         </a>
       </li>
       <li class="nav-item">
-        <a class="nav-link active" href="/tables/<%= encodeURIComponent(Table.TableName) %>/get">
+        <a class="nav-link active" href='<%= basePath %>/tables/<%= encodeURIComponent(Table.TableName) %>/get'>
           Get
         </a>
       </li>
       <li class='nav-item'>
-        <a class='nav-link' href='/tables/<%= encodeURIComponent(Table.TableName) %>/meta'>Meta</a>
+        <a class='nav-link' href='<%= basePath %>/tables/<%= encodeURIComponent(Table.TableName) %>/meta'>Meta</a>
       </li>
     </ul>
   </header>

views/item.ejs

@@ -11,11 +11,11 @@
     <%
       const breadcrumb = [
         {
-          href: '/',
+          href: basePath + '/',
           text: 'Tables',
         },
         {
-          href: `/tables/${encodeURIComponent(TableName)}`,
+          href: `${basePath}/tables/${encodeURIComponent(TableName)}`,
           text: Table.TableName,
           badge: Table.ItemCount,
         },
@@ -94,7 +94,7 @@
           method: 'delete'
         }).then(async (response) => {
           if (response.ok) {
-            window.location = `/tables/<%= encodeURIComponent(TableName) %>`
+            window.location = '<%= basePath %>/tables/<%= encodeURIComponent(TableName) %>'
           } else {
             const responseText = await response.text()
             throw new Error(JSON.parse(responseText).message)