Tidrapportera och fakturera med Kimai och Podman utan root

Det här sätter du upp

Kimai är en tidrapportering för ett team eller en konsultfirma. Du lägger upp kunder, projekt och aktiviteter, alla registrerar sina timmar med en timer eller för hand, och Kimai gör om timmarna till rapporter, exporter i Excel, CSV eller PDF, och fakturor med era timpriser och moms. Den klarar alla valutor, svenska kronor också, och gränssnittet finns på svenska.

Kimai är skapad av Kevin Papst, en fristående utvecklare i Wien i Österrike, och utvecklas öppet tillsammans med användarna på GitHub. Den är öppen källkod under licensen AGPL-3.0. Kevin Papst driver också en färdig molntjänst, Kimai Cloud, och säljer tillägg. Den här guiden använder den officiella containeravbilden, kimai/kimai2, som Kimai-projektet själv ger ut.

Här körs Kimai som en pod under en egen användare som heter kimai, med MariaDB för dess data, bakom Caddy från Podman-guiden.

Varje steg nedan har körts på en nyinstallerad Melonslab VC-P Alloy (2 vCPU, 8 GB) med Debian 13:

• Kimai 2.69.0 startade med MariaDB 11.8, utan några konton tills den första administratören skapades från kommandoraden, och utan möjlighet för besökare att registrera sig.
• Gränssnittet visades på svenska, med svenska datum, svenska talformat och svensk tid, och SEK sattes som valuta för nya kunder.
• Två kunder, ett projekt med budget, två aktiviteter och ett timpris på 950 kr lades upp. Timmar registrerades för hand och med timern.
• En faktura på svenska skapades som PDF, med 25 % moms och en summa i kronor, och timmarna markerades som fakturerade. En rapport exporterades som Excel och som PDF.
• Inloggningsförsök begränsades per besökaradress, över IPv4 och IPv6, och sessionscookien skickades bara över HTTPS.
• Ett mejl för att återställa lösenordet kom fram till en testserver för e-post, med en fungerande inloggningslänk. Utan e-post sa en återställning att ett mejl hade skickats, utan att något skickades.
• I en avlyssning av serverns trafik gjorde Kimai inga externa anslutningar när den startade, när tid registrerades och när fakturor och exporter skapades. Två administratörssidor är undantaget: System > Tillägg hämtar Kimais lista över tillägg från www.kimai.org, och System > Status frågar GitHub efter den senaste versionen.
• En uppdatering från Kimai 2.68.0 till 2.69.0 gick igenom med podman auto-update. Kimai återställdes från en säkerhetskopia till tomma volymer, med sina fakturor, och allt startade igen av sig självt efter en omstart av servern.

Podden använde omkring 200 MB minne, det mesta för MariaDB.

Innan du börjar

Du behöver:

• en server uppsatt som i Podman-guiden, med Caddy igång;
• en A-post och en AAAA-post för time.example.com som pekar på din server.

Exemplen använder time.example.com för Kimai, 203.0.113.10 för serverns IPv4-adress, som ip -brief address show eth0 visar, Exempel AB för ditt eget företag och Nordljus AB för en kund. Byt ut dem genomgående.

1. Skapa användaren

Som root:

useradd -m -s /bin/bash kimai
loginctl enable-linger kimai
machinectl shell kimai@

Allt fram till steg 5 körs som kimai.

2. Skapa hemligheterna

pw=$(openssl rand -hex 24)
printf %s "$pw" | podman secret create kimai-db-password -
printf %s "mysql://kimai:$pw@127.0.0.1:3306/kimai?charset=utf8mb4&serverVersion=11.8.0-MariaDB" | podman secret create kimai-database-url -
unset pw

Den första hemligheten är databaslösenordet, för MariaDB. Kimai vill ha sina databasuppgifter som en enda adress, DATABASE_URL, med samma lösenord i, så det är den andra hemligheten. Båda lagras av Podman, inte i filerna nedan.

3. Definiera podden

mkdir -p ~/.config/containers/systemd
cd ~/.config/containers/systemd

Skapa kimai.pod:

[Pod]
PodName=kimai
# Only Caddy, on this server, can reach Kimai: the port is not open to the internet.
PublishPort=127.0.0.1:8160:8001

[Install]
WantedBy=default.target

Skapa kimai-db.container:

[Container]
ContainerName=kimai-db
Image=docker.io/library/mariadb:11.8
Pod=kimai.pod
Volume=kimai-db:/var/lib/mysql
Environment=MARIADB_DATABASE=kimai MARIADB_USER=kimai MARIADB_RANDOM_ROOT_PASSWORD=1 MARIADB_AUTO_UPGRADE=1
Secret=kimai-db-password,type=env,target=MARIADB_PASSWORD
HealthCmd=healthcheck.sh --connect --innodb_initialized
HealthInterval=10s
Notify=healthy
AutoUpdate=registry

[Service]
Restart=always

Och kimai-app.container:

[Unit]
Requires=kimai-db.service
After=kimai-db.service

[Container]
ContainerName=kimai-app
Image=docker.io/kimai/kimai2:apache
Pod=kimai.pod
Volume=kimai-data:/opt/kimai/var
Environment=DEFAULT_URI=https://time.example.com TRUSTED_PROXIES=203.0.113.10
Environment=TRUSTED_HOSTS=^(time[.]example[.]com|localhost)$
Secret=kimai-database-url,type=env,target=DATABASE_URL
AutoUpdate=registry

[Service]
Restart=always

Vad inställningarna gör:

• DEFAULT_URI är Kimais publika adress, som den sätter i länkarna i sina mejl.
• TRUSTED_PROXIES är adressen som Kimai litar på när den får veta besökarens riktiga adress, och att besökaren kom via HTTPS. Caddys anslutningar kommer in i podden från serverns egen IPv4-adress, som Podman-guiden förklarar, så det är den du anger. Kimai spärrar inloggningen i fem minuter efter fem misslyckade försök från samma adress. Utan den här raden har alla besökare serverns adress, och en persons felskrivningar spärrar alla.
• TRUSTED_HOSTS anger vilka namn Kimai svarar på, och den avvisar anrop till alla andra namn. localhost är till för kontroller inifrån containern, som den nedan. Kimai stänger av återställning av lösenord tills den är satt. Skriv punkterna som [.], som i exemplet.
• kimai:apache är den officiella avbilden med en egen webbserver, Apache, och taggen följer varje ny version av Kimai. Kimai uppdaterar sin databas själv när den startar.
• MariaDB ligger kvar på 11.8, en version med långtidsstöd, och MARIADB_AUTO_UPGRADE uppdaterar dess systemtabeller efter en uppdatering inom den.
• Volymen kimai-data innehåller fakturorna som Kimai skapar, Kimais egen hemliga nyckel, som den skapar vid första starten, och dess cache. Kunder, timmar och inställningar ligger i databasen.

Starta den:

systemctl --user daemon-reload
systemctl --user start kimai-pod
systemctl --user enable --now podman-auto-update.timer

Vid första starten laddas omkring 1,2 GB avbilder ner, och Kimai behöver en minut för att sätta upp sin databas. Den är klar när det här skriver ut 200:

podman exec kimai-app curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8001/en/login

4. Skapa ditt administratörskonto

Kimai startar utan konton, så ingen kan logga in förrän du har skapat ett. Använd Kimais eget kommando, med ditt eget användarnamn och din e-postadress:

podman exec -it --user www-data kimai-app /opt/kimai/bin/console kimai:user:create anna anna@example.com ROLE_SUPER_ADMIN

Kommandot frågar efter ett lösenord på minst 8 tecken och skriver ut "Success! Created user: anna". ROLE_SUPER_ADMIN ger kontot alla rättigheter, även till systeminställningarna. --user www-data kör kommandot som den användare som Kimais webbserver körs som, så att det inte lämnar filer i volymen som Kimai inte kan läsa.

5. Sätt Caddy framför

Gå tillbaka till root med exit, byt till machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:

time.example.com {
    reverse_proxy 127.0.0.1:8160
}

Starta om Caddy med systemctl --user restart caddy, öppna https://time.example.com och logga in med användarnamnet och lösenordet från steg 4.

Det finns ingen sida för att registrera sig: du skapar alla konton själv under System > Användare. Var och en kan slå på tvåfaktorsautentisering i sin profilmeny uppe till höger, under Tvåfaktor (2FA).

6. Använd Kimai på svenska

Första gången du loggar in frågar en kort guide efter dina inställningar. För att använda Kimai på svenska väljer du:

• Language: Svenska;
• Time, date and currency format: Svenska (Sverige), som skriver datum som 2026-10-14 och belopp som 1 234,56 kr;
• Timezone: Europe / Stockholm.

Guiden byter till svenska så fort du går vidare med Nästa. Var och en kan ändra det senare i sin profilmeny under Preferenser. Resten av den här guiden använder de svenska namnen i gränssnittet.

Kimais standard för nya användare är engelska och UTC. För att göra svenska till standard för alla du skapar öppnar du System > Systeminställningar, och under Användare sätter du Tidszon till Europe / Stockholm, Språk till Svenska och Tid, datum och valutaformat till Svenska (Sverige). Välj sedan Spara.

7. Ställ in ditt företag

Sidan med systeminställningar har ett formulär per område, vart och ett med en egen Spara-knapp. Under System > Systeminställningar:

• Mitt företag: fyll i Företagsnamn, som Kimai visar uppe till vänster, och sätt Valuta till svensk krona.
• Kund: sätt Land till Sverige, Språk till Svenska och Tidszon till Europe / Stockholm.
• Fakturor: Format för fakturanummer är {Y}/{cy,3} som standard, året och en räknare per kund och år, till exempel 2026/001. Ändra det om ni numrerar på ett annat sätt.

Nya kunder får den valuta, det land, det språk och den tidszon du ställer in här. Valutan sparas på varje kund, så du kan fakturera en kund i euro och resten i kronor.

8. Kunder, projekt och aktiviteter

Timmar registreras på en kund, ett av dess projekt och en aktivitet. Under Administration:

1. Kund > Skapa. Skapa först ditt eget företag, Exempel AB: Kimai använder en kund som avsändare på fakturorna. Fyll i Namn, under Adress ert Företagsnamn, adress och Land, och under Fakturor ert VAT-ID / orgnr, och välj Spara.
2. Skapa kunden du fakturerar, Nordljus AB, på samma sätt. Valuta är redan svensk krona.
3. På kundens sida väljer du + bredvid Avgifter, skriver 950 som Pris och väljer Spara. Det blir timpriset för alla kundens projekt; låt Fast pris vara avstängt. Ett pris kan också sättas på ett projekt, en aktivitet eller en enskild användare.
4. Projekt > Skapa, välj Kund, ge projektet ett Namn, till exempel Ny webbplats, och om du vill en Finansplan, alltså en budget i kronor, och välj Spara. Projektets sida visar hur mycket av budgeten som är använd.
5. Aktiviteter > Skapa, till exempel Utveckling och Möte. Utan Projekt kan en aktivitet användas i alla projekt.

9. Registrera tid

Under Tidsrapportering > Min tidrapport:

• Play-knappen högst upp, Påbörja tidtagning, startar timern: välj kund, projekt och aktivitet, och välj Spara med Längd / Till tomt. Knappen blir en stoppknapp som visar tiden som går; välj den när du är klar.
• Skapa lägger till timmar i efterhand: ett datum, en starttid och en längd, till exempel 2:30.

Arbetsvecka visar en vecka som ett rutnät att fylla i, och Kalender visar dina timmar i en kalender. Under Rapporter summerar Kimai timmar och belopp per användare, kund och projekt.

10. Fakturor

En faktura behöver först en mall. Under Fakturor > Fakturamall > Skapa:

• Namn, till exempel Standard, och Titel, rubriken på fakturan, till exempel Faktura.
• Fakturaavsändare: ditt eget företag från steg 8.
• Betalningsvillkor, till exempel Betalning inom 30 dagar., Bankkonto, till exempel ert bankgironummer, och Betalningsperiod i dagar.
• Momssats: 25 för 25 % moms.
• Språk: Svenska.
• Fakturadokument: låt det stå på Faktura, standardvalet, som ger en PDF. Listan har en Faktura till, under HTML, som ger en HTML-fil i stället. Kalkylerad summa ger som standard en rad per post.

Under Fakturor > Skapa faktura väljer du sedan Kund, kontrollerar Tidsintervall och väljer Sök. Förhandsgranskningen visar kunden, timmarna och summan med moms. Förhandsgranska visar själva fakturan, och Spara skapar den: den får nästa nummer och sparas under Fakturahistorik, där Ladda ner ger dig PDF:en, och dess timmar markeras som exporterade, så att de inte faktureras två gånger.

Vår testfaktura, på svenska, hade avsändaren och kunden med sina momsregistreringsnummer, ett förfallodatum 30 dagar fram, en rad per post à 950,00 kr i timmen, nettobeloppet, 25 % moms och summan i kronor. I Fakturahistorik markerar du en faktura som betald eller makulerar den.

11. Exportera en rapport

Tidsrapportering > Exportera ger dig timmarna för en kund eller en period som en fil, utan att skapa en faktura, till exempel för att skicka med en faktura från ditt bokföringsprogram. Välj filter och Sök, och sedan CSV, Excel eller PDF. PDF:en öppnas i en ny flik, med en sammanfattning per kund och projekt och en fullständig lista över posterna. Markera som exporterat markerar timmarna som exporterade, precis som en faktura gör.

12. E-post

Kimai skickar e-post för att återställa lösenord, från Jag har glömt mitt lösenord på inloggningssidan. Den här guiden sätter inte upp e-post, och utan den:

• säger en begäran om återställning att "Ett e-postmeddelande har skickats med en länk för att återställa ditt lösenord", men inget skickas;
• ber Kimai den användaren om ett nytt lösenord vid nästa inloggning, efter en begäran om återställning.

Inloggning med lösenord fungerar som vanligt, och du kan sätta ett nytt lösenord åt vem som helst under System > Användare, i menyn bredvid användaren, under Lösenord.

För att skicka e-post pekar du Kimai mot din e-postleverantörs SMTP-server. Kimai vill ha servern, kontot och lösenordet som en enda adress. Som kimai sparar du den som en hemlighet, med ditt eget konto, lösenord och din server:

printf %s 'smtp://time%40example.com:the-smtp-password@mail.example.com:587' | podman secret create kimai-mailer-url -

@ i kontonamnet skrivs %40. Skriv andra tecken i lösenordet på samma sätt, till exempel %2F för / och %3A för :, eller välj ett lösenord med bara bokstäver och siffror. Lägg sedan till de här raderna i kimai-app.container, med din avsändaradress:

Environment=MAILER_FROM=time@example.com
Secret=kimai-mailer-url,type=env,target=MAILER_URL

Och starta om:

systemctl --user daemon-reload
systemctl --user restart kimai-app

Port 587 använder STARTTLS. För port 465, som använder TLS från början, börjar du adressen med smtps:// och avslutar den med :465. Vi testade att skicka till en testserver för e-post på samma server, utan TLS; att skicka via en riktig e-postleverantör har vi inte testat.

13. Säkerhetskopiera

Som kimai:

umask 077
mkdir -p ~/backup
podman exec kimai-db sh -c 'mariadb-dump -ukimai -p"$MARIADB_PASSWORD" --single-transaction kimai' > ~/backup/kimai-db.sql
podman volume export kimai-data > ~/backup/kimai-data.tar

Dumpen innehåller kunder, projekt, timmar, användare och inställningar, och körs medan Kimai fortsätter att fungera. Volymen innehåller PDF-fakturorna som Kimai har skapat och dess hemliga nyckel. Kopiera ~/backup till en annan maskin, till exempel med restic, och förvara den säkert: den innehåller alla era timmar och era kunders uppgifter.

För att återställa till en tom pod, som kimai, med säkerhetskopian i ~/backup:

systemctl --user stop kimai-pod
podman volume rm kimai-db kimai-data
podman volume create kimai-data
podman volume import kimai-data ~/backup/kimai-data.tar
systemctl --user start kimai-db
podman exec -i kimai-db sh -c 'mariadb -ukimai -p"$MARIADB_PASSWORD" kimai' < ~/backup/kimai-db.sql
systemctl --user start kimai-app

Genom att bara starta databasen först läses säkerhetskopian in innan Kimai sätter upp en tom databas. På en ny server följer du först steg 1 till 3, men återställer innan du skapar ett konto i steg 4.

14. Uppdatera

podman auto-update letar en gång om dagen efter nya avbilder av Kimai och MariaDB och startar om podden när någon har ändrats. Kimai uppdaterar sin databas när den startar. För att uppdatera direkt:

podman auto-update

Vill du själv bestämma när du uppdaterar byter du apache i kimai-app.container mot en version, till exempel 2.69.0 från avbildens lista över taggar, som är samma avbild, tar bort raden AutoUpdate=registry och byter version när du vill uppdatera. Håll i båda fallen dina säkerhetskopior aktuella, och läs versionsinformationen på Kimais GitHub-sida före större uppdateringar.

Felsökning

"För många misslyckade inloggningsförsök, försök igen om 5 minuter." för alla på en gång. TRUSTED_PROXIES saknas eller anger fel adress, så Kimai ser varje besökare som servern. Den måste vara serverns IPv4-adress, inte 127.0.0.1. Rätta den i kimai-app.container, kör sedan daemon-reload och starta om kimai-app.

Varje sida ger fel 400. Namnet i webbläsarens adressfält stämmer inte med TRUSTED_HOSTS. Kontrollera namnet i kimai-app.container, med varje punkt skriven som [.].

Jag har glömt mitt lösenord ger fel 503. TRUSTED_HOSTS är inte satt; Kimais logg, podman logs kimai-app, säger "Password reset is deactivated". Lägg till raden från steg 3.

Kimai ber om ett nytt lösenord efter inloggningen. Någon har begärt en återställning av lösenordet för det kontot. Sätt ett nytt lösenord, så frågar den inte igen.