How to Set Up a New Coffee Auction in the V-Auction System

Source: Verified from sensible.coffee.rental source code (~/git/sensible.coffee.rental/) and database schema on coffeesites-db-0. Not written from memory or speculation.

Overview

Setting up a new auction is done through the admin area of the auction site. The admin interface is a JSP-based CRUD system built on the SDF framework — it auto-generates forms from the entity model, so what you see is what the database schema dictates.

Access: https://<your-coffee-site>/admin Login: Admin user credentials (configured per site)

Step 1 — Log In to the Admin Area

Navigate to https://<site-domain>/admin and log in with an admin account. The admin area has several top-level sections:

Auction Dashboard — auctions, lots, and quick actions
Settings — site configuration (AdminConfigCommand)
Invoice — cart invoices and credit notes
User — user management
Reports — sales reports, bidding reports, lot reports

Step 2 — Create a New Auction

From the Auction Dashboard, click "Add New Auction" (or navigate to Auctions → Add).

The auction entity has the following fields you need to configure:

Core Fields

Field	Description
Name	Display name for the auction
Description	Long text — appears on the auction page
Slug	URL-friendly identifier (auto-generated, must be unique)
Start Date	When the auction opens
End Date	When the auction closes (for timed/helmsman)

Status

Value	Meaning
DRAFT	Work in progress — not visible to public
PUBLISHED	Live — visible to bidders
ARCHIVE	Closed — historical record

Auction Style (`auction_style`)

Style	Description
Online/Timed	Standard timed auction with incremental bidding
Live/In-room	Runs alongside a real auctioneer, one lot at a time
Helmsman	All lots end together — bidding on one extends all
Helmsman Timed	Lots tied to auction end date
Reverse	Price decreases over time
Commodity	Hybrid of live and helmsman

Additional Configuration

Field	Description
Prebidding Allowed	Allow bids before the auction start date
Prebidding End Date	When prebidding stops
Registration Fee	Fee required to register for this auction
Notice to Purchasers	Terms text shown to buyers
Terms and Conditions File	Upload a T&C document
Registration Info	Instructions for bidders
Email Subject/Text/CC	Custom email templates for auction notifications
Auction Live Stream	Embed code for live stream (if applicable)
Maximum Sample Purchase	For coffee: limit on sample orders per user
Sample Description	Description for sample purchasing

Live Auction Specific

Field	Description
Live Auction Status	Controls the helm/rostrum state
Current Live Lot ID	Which lot the auctioneer is currently calling
Before/After/Pause Live Auction Message	Messages shown during different states

After filling in the required fields, click Save. The auction is created with DRAFT status.

Step 3 — Add Lots to the Auction

Lots can be added in three ways:

Option A: Add Individual Lots

From the auction edit page, click "Add Lot". Each lot requires:

Field	Description
Lot Number	Display number (e.g., "LOT-001")
Short Name	Brief title shown in listings
Description	Full lot description (long text)
Opening Bid	Starting price
Reserve	Minimum acceptable bid (can be 0 for no reserve)
Increment	Minimum bid step
Start Date	When bidding opens for this lot
End Date	When bidding closes
Overtime Period	Seconds added when a bid comes in near closing
Overtime Active	Enable/disable overtime bidding

Additional options per lot: - Buy Now Price / Buy Now Only — fixed-price purchase - Sealed Bidding Only — blind bids (no cross-validation) - Preview Lot — bidding ends but no winner is auto-selected - Featured — highlight in listings - Guide Price — estimated value display - Postage — shipping cost - Video HTML — embed a video - Other Info — freeform HTML (used for dinner banners, custom links)

Option B: Bulk Upload Lots

From the dashboard, click "Bulk Upload Lots". This uses a CSV/XLS import:

Download or prepare a CSV with lot data matching the entity fields
Upload via admin/bulk_register_lots
The system maps columns to lot fields and creates them in bulk

The import validates against BulkRegisterLotNullValidation.java rules — required fields must be present.

Option C: Bulk Upload Images

After lots exist, click "Bulk Upload Images" (admin/bulk_upload_images). This matches images to lots by lot number or reference ID and attaches them to the lot's image gallery.

Step 4 — Configure Site Settings

From the admin area, go to Settings → Config. This controls site-level behavior:

Mandrill SMTP settings — email delivery configuration
WordPress URL — blog integration (if used)
Site identifier — unique site tag
Header visibility — show/hide header elements
Currency — display currency
Deepl API key — translation service

These settings are stored in the admin_config table and apply site-wide, not per-auction.

Step 5 — Manage Users

Upload/Invite Users

Admin can register users manually or send invitations
Users register via the public site if registration is open

Approve Users

Go to Admin → Approve Auction Users (admin/approve_auction_users)
Review and approve registered bidders before the auction

Activate Users

User activation can be automatic or manual depending on registration_process setting
PIN number support is available (field exists on auction entity)

Step 6 — Set Up Watchlists (Admin Rostrum)

For podium and multi-lot events, you can create Admin Watchlists to control what appears on the rostrum display:

Go to Admin Pages → Content → Admin Watchlist
Create a watchlist with:
Unique name
Top limit — how many lots display (recommend 1-5)
Show closed lots — toggle
Active — must be checked to appear in bulk edit
Sort order — display order (10, 20, 30...)
Save
Go to View Lots → Bulk Edit — there's a new column for watchlists
Assign lots to watchlists (Ctrl+click for multiple)
Access via View Rostrum in the admin auction page

Step 7 — Publish the Auction

When ready:

Edit the auction
Change status from DRAFT to PUBLISHED
The auction becomes visible to the public
For live auctions, use the Helm (/auction/helm) to control lot progression in real-time

Live Auction Control

Helm page (/auction/helm): Auctioneer controls which lot is active, starts/ends bidding
Rostrum page (/auction/rostrum): Display showing current podium standings
Slideshow page (/auction/slideshow): Public-facing lot display

Step 8 — Post-Auction

After the auction closes:

Set status to ARCHIVE
Export reports from Reports section:
Auction Sales Report — revenue summary
Buyer's Lot Report — per-buyer purchases
Vendor Sales Report — per-vendor sales
Unsold Lots Report — lots that didn't sell
Bidding Report — bid history
Process invoices via the Invoice section
Clear down data for next auction (see separate doc)

Database Reference

Auction table columns verified from coffeesites-db-0:

id, description, end_date, featured, name, need_to_register, slug,
start_date, status, after_live_auction_message, prebidding_allowed,
before_live_auction_message, live_auction_status, pause_live_auction_message,
prebidding_enddate, current_live_lot_id, auction_live_stream,
registration_process, notice_to_purchasers, terms_and_conditions_file,
registration_fee, registration_info, auction_style, helmsman_auction_status,
helmsman_extend_seconds, helmsman_pause_millis, practice, lot_payment_disabled,
promotion_text, menu_bg_color, stripe_config_id, user_id,
maximum_sample_purchase, sample_description, send_approval_emails,
send_rejected_emails, send_tracking_email, display_scores,
activate_increment_swapping, increment_update_date, estate_auction,
biddingAgreement, defaultTAndC, email_subject, email_text, email_cc,
display_ranks, location_id

Lot table key columns:

id, biddingSuspended, buy_now_only, buy_now_price, description, end_date,
featured, increment, sort_order, opening_bid, overtime_active, overtime_period,
paid_for, preview_lot, ref_id, reserve, sealed_bidding_only, short_name,
show_reserve_temperature, slug, status, video_html, winner_notified,
final_sale_price, lot_number, postage, start_date, viewing_only,
auction_id, user_id, guide_price, map_html, vendor_id, location_id,
asking_price, dispatched, internal_reference, description_excerpt, boxes,
pounds, winner_details, packing_cost_per_pound, score, secondary_increment,
farm_url, farmer_name, random_str

Source Code Reference

Component	File Path
Auction entity	`sensible.coffee.rental/src/main/java/.../entity/Auction.java`
Lot entity	Database schema (`DESCRIBE lot` on `coffeesites-db-0`)
Admin dashboard	`src/main/webapp/WEB-INF/jsp/admin/auction-area-dashboard.jsp`
Auction edit	`src/main/java/.../admin/area/AuctionEditCommand.java`
Admin config	`src/main/java/.../commands/admin/AdminConfigCommand.java`
Bulk upload lots	`src/main/webapp/WEB-INF/jsp/admin/bulk_register_lots.jsp`
Bulk upload images	`src/main/java/.../commands/admin/BulkUploadImagesCommandImpl.java`
User approval	`src/main/webapp/WEB-INF/jsp/admin/approve_auction_users.jsp`
Helm control	`src/main/webapp/WEB-INF/jsp/auction/helm.jsp`
Rostrum	`src/main/webapp/WEB-INF/jsp/auction/rostrum.jsp`
Auction styles enum	`Auction.java` (line ~93: `AUCTION_STYLE`)

What This Doc Doesn't Cover

Provisioning a new Coffee site (infrastructure, Docker Swarm, HAProxy, DNS) — that's a separate process handled by the build scripts at /home/ian/docker/create-scripts/coffee.create
Bulk upload CSV format — needs to be reverse-engineered from the import code
Clear-down procedure — exists as a 2020 Confluence page, needs updating
Email event configuration — Mandrill template setup per auction
Stripe/payment gateway setup — per-site stripe_config_id configuration