A simple perl server with containerization and VSCode dev container support.
- Lightweight Perl web server w/ Mojolicious
- Vue 3 SPA frontend with Vite build system
- OpenAPI schema support w/ Swagger page.
- Multiple logging schemes available out of box.
- PostgreSQL database integration.
- DevContainer support w/ external Docker containerization.
- Integrated Claude Code support.
- Node.js LTS (for frontend development)
- Docker & Docker Compose
- VSCode (recommended for DevContainer support)
- Open repository with VSCode
code . - Use VSCode command 'Open Folder In Container...'
- Wait until postcreate.sh and poststart.sh are completed (installs dependencies and builds frontend)
- Run
docker compose up --build --watch - "Hello, perld!" will be served at localhost:3000, with swagger frontend at localhost:3000/swagger
-
Install Perl dependencies:
cpanm --installdeps --notest . -
Install frontend dependencies and build:
cd frontend npm install npm run build cd ..
-
Start the Mojolicious server:
morbo ./script/hello-perld
The application will be available at http://localhost:3000
docker compose up --buildThe frontend is a Vue 3 single-page application built with Vite.
For the best development experience, run the Vite dev server and Mojolicious backend separately:
-
Terminal 1 - Start Mojolicious backend:
morbo ./script/hello-perld
-
Terminal 2 - Start Vite dev server:
cd frontend npm run devThe Vite dev server runs at http://localhost:5173 and proxies API calls to the Mojolicious backend at http://localhost:3000
To build the frontend for production:
cd frontend
npm run buildThis builds assets to lib/HelloPerld/Public/dist/ which are served by Mojolicious.
hello-perld/
├── frontend/ # Vue 3 SPA frontend
│ ├── src/
│ │ ├── components/ # Vue components
│ │ ├── views/ # Page views
│ │ ├── router/ # Vue Router config
│ │ ├── assets/ # CSS and static assets
│ │ ├── App.vue # Root component
│ │ └── main.js # Entry point
│ ├── index.html # HTML template
│ ├── vite.config.js # Vite configuration
│ └── package.json # Frontend dependencies
├── lib/HelloPerld/ # Perl backend
│ ├── Public/ # Static assets
│ │ └── dist/ # Built frontend assets (generated)
│ └── Templates/ # Mojolicious templates
├── script/ # Perl scripts
└── Dockerfile # Multi-stage build (Node + Perl)
---
## ssh-agent Setup (for use with Git SSH within Dev Container)
### Prep WSL2 (Ubuntu/Debian shown—adapt as needed), Ensure OpenSSH client & ssh-agent
sudo apt-get update sudo apt-get install -y openssh-client
### Start (and persist) an ssh-agent in WSL2
Put this tiny helper in your shell init so a single socket lives across sessions:
### Add to ~/.bashrc (or ~/.zshrc)
if [ -z "$SSH_AUTH_SOCK" ]; then SOCK="$HOME/.ssh/agent.sock" if [ -S "$SOCK" ]; then export SSH_AUTH_SOCK="$SOCK" else mkdir -p "$HOME/.ssh" eval "$(ssh-agent -a "$SOCK" -s)" >/dev/null export SSH_AUTH_SOCK="$SOCK" fi fi
Reload your shell:
`exec $SHELL -l`
### Add your key to the agent
ssh-add ~/.ssh/id_ed25519
ssh-add -l # should list your key fingerprint
Tip: First confirm this works directly in WSL:
ssh -T git@github.com
### Expect: "Hi <username>! You've successfully authenticated..."
If that succeeds, your host (WSL2) SSH is good.
### Validate in dev container
Open the folder in WSL (VS Code: “Open Folder in WSL”), then Reopen in Container.
Inside the container’s terminal:
echo "$SSH_AUTH_SOCK" # should be /ssh-agent ls -l "$SSH_AUTH_SOCK" # should be a socket file ssh -T git@github.com # should greet you (no password prompt)
Ensure the repo remote uses SSH, not HTTPS:
git remote -v git remote set-url origin git@github.com:/.git
git fetch, git pull, git push should now work from inside the dev container.
## Common issues & fixes
“Permission denied (publickey)”
In WSL (not container): `ssh-add -l` must list your key. If empty, `ssh-add ~/.ssh/<yourkey>`.
Inside container: `echo $SSH_AUTH_SOCK` should be /ssh-agent and `ls -l /ssh-agent` should show a socket.
Ensure devcontainer.json used `${localEnv:SSH_AUTH_SOCK}` (not ${env:...}) so it resolves in the WSL VS Code context.
If that fails, it may be possible that there are multiple agents available and that is causing a conflict in forwarding the correct one.
### In WSL2: run one pinned ssh-agent and load keys
Put the agent on a stable path so VS Code always mounts the same socket.
### In WSL2
pkill ssh-agent 2>/dev/null || true rm -f ~/.ssh/agent.sock eval "$(ssh-agent -a "$HOME/.ssh/agent.sock" -s)" ssh-add -D ssh-add ~/.ssh/id_ed25519 # or your key file ssh-add -l # should list your key(s)
Verify you’re using the pinned agent:
SSH_AUTH_SOCK=$HOME/.ssh/agent.sock ssh-add -l # must list the same keys echo "$SSH_AUTH_SOCK" # ideally /home//.ssh/agent.sock